teams

A small Go application to visualize GitHub teams and their members. Helps to find out:

• who is in which team
• who is not in any team
• teams parent-child relations
• teams that are logically a child of another team

Example

For a fake GitHub organization shiny-platpus output would look like this:

digraph G {
    node [shape=record; fontname=Monospace; fontsize=10; penwidth=1.5];

    "animals" [ label="{*animals*|guineveresaenger|joeduffy|kimberleyamackenzie|roothorp|susanev|thomas11}" ]
    "platypuses" [ label="{*platypuses*|joeduffy|guineveresaenger|susanev|thomas11}" ]
    "unicorns" [ label="{*unicorns*|susanev|thomas11|kimberleyamackenzie|roothorp}" ]

    "animals" -> "platypuses" [penwidth=1.5];
    "animals" -> "unicorns" [penwidth=1.5];
}

Running

Binary

Download binary from latest release.

$ teams --help
Usage:
  app [OPTIONS]

Application Options:
      --token=        GitHub access token [$GITHUB_TOKEN]
      --org=          GitHub organization name [$GITHUB_ORG]
      --hide-members  Hide Team Members on the diagram [$HIDE_MEMBERS]
      --template=     Go template (optional) [$TEMPLATE]
      --output=       Output file (default: output/graph.dot) [$OUTPUT]

Help Options:
  -h, --help      Show this help message

$ teams --token ghp_... --org shiny-platypus --output output/graph.dot

Docker Compose

See docker-compose.yml for example of running the application with Docker Compose.

Set GITHUB_TOKEN and GITHUB_ORG environment variables.

Run the application:

$ docker-compose up
 ⠿ Container teams     Created
 ⠿ Container graphviz  Created
Attaching to graphviz, teams
teams     | 2022/12/28 12:00:00 Getting organization ID...
teams     | 2022/12/28 12:00:00 Getting organization members...
teams     | 2022/12/28 12:00:00 Getting organization teams...
teams     | 2022/12/28 12:00:05 Rendering template...
teams     | 2022/12/28 12:00:05 Done!
teams exited with code 0
graphviz exited with code 0

Open output/graph.png or output/graph.svg.

Local development

Pre-requisites: Go >=1.19, Graphviz.

Create GitHub Personal Access Token with read:org scope.

Clone repository and run:

export GITHUB_TOKEN=your_token
export GITHUB_ORG=your_org
make clean run

Example output:

2022/12/28 12:00:00 Getting organization ID...
2022/12/28 12:00:00 Getting organization members...
2022/12/28 12:00:00 Getting organization teams...
2022/12/28 12:00:05 Rendering template...
2022/12/28 12:00:05 Done!

Open output/graph.png or output/graph.svg.

Common problems

export GITHUB_TOKEN=<value>
export GITHUB_ORG=<value>
make clean run
2023/02/08 14:56:28 Getting organization ID...
2023/02/08 14:56:28 Getting organization members...
2023/02/08 14:56:28 Getting organization teams...
2023/02/08 14:56:36 Rendering template...
2023/02/08 14:56:36 Done!
make: dot: No such file or directory
make: *** [run-graphviz] Error 1

Solution: Install Go >=1.19 and Graphviz