Team manager is a utility that allows an organization owner to:
- add or remove people from existing teams and / or assign people for GitHub team review assignments;
- configure repository permissions for teams and individual users;
- keep track of all "outside collaborators" and the reason why they are outside collaborators;
- check if all teams have enough reviewers;
- Retrieve all teams, associated members and code review assignments in an organization into a configuration file.
- Sync local configuration file into GitHub.
- Add and / or remove new members to / from teams.
- Exclude team members from code review assignments.
- Create or delete teams that are added or removed from the local configuration file.
- Sync team and user permissions of repositories.
- Check Status of teams. Useful to know if teams have enough reviewers.
- GitHub action (see example below)
- Retrieve excluded team members from the code review assignments (not provided by GitHub API).
make team-manager-
Generate a GitHub token that has
admin:organdpublic_repo. direct link -
Generate configuration for your organization
$ ./team-manager init --org cilium
Retrieving configuration from organization...
Creating configuration file "cilium-team-assignments.yaml"...- Modify your file accordingly the available options, for example (the yaml
comments will not show up in the generated file and will be removed every time
./team-manageris executed):
organization: cilium
repositories:
# Repository name
cilium:
# User-specific permissions. Always prefixed with 'USER'.
# Valid options: 'USER-ADMIN', 'USER-MAINTAIN', 'USER-WRITE', 'USER-TRIAGE', 'USER-READ'
USER-READ:
- ciliumbot
# Team-specific permissions.
# Valid options: 'ADMIN', 'MAINTAIN', 'WRITE', 'TRIAGE', 'READ'
WRITE:
- bpf
- sig-policy
members:
aanm:
# User ID, retrieved from GitHub
id: MDQ6VXNlcjU3MTQwNjY=
# User real name, useful to know which person is behind a GitHub username.
name: André Martins
# Slack user ID, to ping folks on Slack.
slackId: U3Z10R6HW
borkmann:
id: MDQ6VXNlcjY3NzM5Mw==
name: Daniel Borkmann
joestringer:
id: MDQ6VXNlcjEyNDMzMzY=
name: Joe Stringer
# The list of 'outsideCollaborators' is automatically derived from the list of users that don't
# belong to the organization but have access to at least one of the repositories
# of the organization.
outsideCollaborators:
ciliumbot:
reason: "Only has access to some repositories"
# List of teams that belong to the organization.
teams:
# Team Name
Cilium Teams:
# team ID, retrieved from GitHub
id: T_kwDOAUFEZs4Ah5D3
# team restID, retrieved from GitHub
restID: 8884471
# Team's description
description: Teams and sigs used for Cilium projects
# Team's privacy settings. Valid values: VISIBLE|SECRET
privacy: VISIBLE
# Teams that are children of this parent team
children:
# Team Name
ebpf:
# team ID, retrieved from GitHub
id: MDQ6VGVhbTQ5MjY2ODE=
# team restID, retrieved from GitHub
restID: 4926681
# Team's description
description: All code related with ebpf.
# List of members' logins that belong to this team.
members:
- aanm
- borkmann
- joestringer
codeReviewAssignment:
# algorithm, currently can be LOAD_BALANCE or ROUND_ROBIN.
algorithm: LOAD_BALANCE
# set 'true' if codeReviewAssignment should be enabled.
enabled: true
# Notify the entire team of the PR if it is delegated.
notifyTeam: false
# List of members that should be excluded from receiving reviews, and
# an optional reason.
excludedMembers:
# GitHub login name (username).
- login: aanm
reason: Want to be part of team 'bpf' but will not be assigned to leave
reviews.
# The number of team members to assign.
teamMemberCount: 1
# Team's privacy settings. Valid values: VISIBLE|SECRET
privacy: VISIBLE
# Team Name
policy:
id: MDQ6VGVhbTI1MTk3ODY=
restID: 8884472
description: All control plane code related with Policy
members:
- aanm
- joestringer
codeReviewAssignment:
algorithm: LOAD_BALANCE
enabled: true
notifyTeam: true
teamMemberCount: 1
privacy: SECRET
# List of members that should be excluded from review assignments for the teams
# that they belong. This list can exist for numerous reasons, person is
# currently PTO or busy with other work.
excludeCodeReviewAssignmentFromAllTeams:
- borkmann- Once the changes stored in a local configuration file, run
./team-manager push --org cilium:
$ ./team-manager push --config-filename ./cilium-team-assignments.yaml
Local config out of sync with upstream: Unified diff:
--- local
+++ remote
@@ -1,11 +1,11 @@
config.TeamConfig{
ID: "MDQ6VGVhbTI1MTk3Nzk=",
- Members: {"aanm", "borkmann", "joestringer"},
+ Members: {"borkmann", "joestringer"},,
CodeReviewAssignment: config.CodeReviewAssignment{
Algorithm: "LOAD_BALANCE",
Enabled: true,
ExcludedMembers: nil,
NotifyTeam: false,
TeamMemberCount: 1,
},
}
Going to submit the following changes:
Team: bpf
Adding members: aanm
Removing members:
Continue? [y/n]: y
Adding member aanm to team bpf
Do you want to update CodeReviewAssignments? [y/n]: y
Excluding members from team: bpf
Excluding members from team: policyStarting with v1.0.0, team-manager has the ability to also sync repository and members permissions. Before changing the file locally to push new changes, it is important to always perform a 'sync':
$ ./team-manager sync --config-filename ./team-assignments.yamlThen, after modifying the file on team-assignments.yaml, push the changes:
$ ./team-manager push --config-filename ./team-assignments.yamlOn a large GitHub organization, it might be difficult to control who can create
repositories. Thus, when running team manager with a GitHub action, it should
run with --repositories=false and --members=false otherwise the GitHub
action might override repository permissions that were set from the web-ui
and remove or add members to the organization that were previously added or
removed from the web-ui.
name: Team management
on:
push:
branches:
- main
jobs:
sync:
# if: github.repository == '<my-org>/<my-repo>'
name: Team sync
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
- uses: docker://quay.io/cilium/team-manager:v1.0.0
name: Sync team
with:
entrypoint: team-manager
# With --repositories=false --members=false, it will have the same
# behavior as <= v0.0.8.
args: push --force --repositories=false --members=false --config-filename ./team-assignments.yaml
env:
GITHUB_TOKEN: ${{ secrets.ADMIN_ORG_TOKEN }}To disable code review assignments, the GitHub user can either set its status as 'busy' or the team maintainer can exclude them from the list of reviewers.
Since the team maintainer can't control the status of the user, it is important to retrieve the list of teams that don't have enough reviewers, by checking which users have their status as 'busy' or the ones that are excluded from reviews.
$ ./team-manager status --config-filename ./cilium-team-assignments.yaml
Checking status of "aanm"
Checking status of "joestringer"
Checking status of "borkmann"
Team "bpf" with 3 members doesn't have enough reviewers:
- aanm - excluded
- joestringer - busy
- borkmann - ok- Use 'sync' to sync the upstream configuration with the local file. It will fetch the information from GitHub and merge it with the local file.
$ ./team-manager sync --config-filename ./team-assignments.yaml