Skip to content

Commit a6334ef

Browse files
aanmaanm
committed
add documentation for new features
Signed-off-by: André Martins <[email protected]>
1 parent 133b0d9 commit a6334ef

8 files changed

+211
-72
lines changed

‎README.md

+134-35
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
# Team manager
22

3-
Team manager is a utility that allows an organization owner to add or remove
3+
Team manager is a utility that allows an organization owner to:
4+
- add or remove
45
people from existing teams and / or assign people for [GitHub team review
5-
assignments](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/managing-code-review-assignment-for-your-team).
6+
assignments](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/managing-code-review-assignment-for-your-team);
7+
- configure repository permissions for teams and individual users;
8+
- keep track of all "outside collaborators" and the reason why they are outside
9+
collaborators;
10+
- check if all teams have enough reviewers;
611

712
## Features
813

@@ -11,14 +16,16 @@ assignments](https://docs.github.com/en/github/setting-up-and-managing-organizat
1116
- [X] Sync local configuration file into GitHub.
1217
- [X] Add and / or remove new members to / from teams.
1318
- [X] Exclude team members from code review assignments.
19+
- [x] Create or delete teams that are added or removed from the local
20+
configuration file.
21+
- [x] Sync team and user permissions of repositories.
22+
- [x] Check Status of teams. Useful to know if teams have enough reviewers.
1423
- [X] GitHub action (see example below)
1524

1625
## Missing features
1726

1827
- [ ] Retrieve excluded team members from the code review assignments
1928
(not provided by GitHub API).
20-
- [ ] Create or delete teams that are added or removed from the local
21-
configuration file.
2229

2330
# Build
2431

@@ -44,8 +51,18 @@ Creating configuration file "cilium-team-assignments.yaml"...
4451

4552
```yaml
4653
organization: cilium
47-
slackWorkspace: cilium.slack.com
48-
# List of members that belong to the organization, ordered by GitHub login (username).
54+
repositories:
55+
# Repository name
56+
cilium:
57+
# User-specific permissions. Always prefixed with 'USER'.
58+
# Valid options: 'USER-ADMIN', 'USER-MAINTAIN', 'USER-WRITE', 'USER-TRIAGE', 'USER-READ'
59+
USER-READ:
60+
- ciliumbot
61+
# Team-specific permissions.
62+
# Valid options: 'ADMIN', 'MAINTAIN', 'WRITE', 'TRIAGE', 'READ'
63+
WRITE:
64+
- bpf
65+
- sig-policy
4966
members:
5067
aanm:
5168
# User ID, retrieved from GitHub
@@ -60,35 +77,62 @@ members:
6077
joestringer:
6178
id: MDQ6VXNlcjEyNDMzMzY=
6279
name: Joe Stringer
63-
# List of teams that belong to the organization, ordered by team names.
80+
# The list of 'outsideCollaborators' is automatically derived from the list of users that don't
81+
# belong to the organization but have access to at least one of the repositories
82+
# of the organization.
83+
outsideCollaborators:
84+
ciliumbot:
85+
reason: "Only has access to some repositories"
86+
# List of teams that belong to the organization.
6487
teams:
65-
bpf:
88+
# Team Name
89+
Cilium Teams:
6690
# team ID, retrieved from GitHub
67-
id: MDQ6VGVhbTI1MTk3Nzk=
68-
# List of members' logins that belong to this team.
69-
members:
70-
- aanm
71-
- borkmann
72-
- joestringer
73-
# codeReviewAssignment
74-
codeReviewAssignment:
75-
# algorithm, currently can be LOAD_BALANCE or ROUND_ROBIN.
76-
algorithm: LOAD_BALANCE
77-
# set 'true' if codeReviewAssignment should be enabled.
78-
enabled: true
79-
# Notify the entire team of the PR if it is delegated.
80-
notifyTeam: false
81-
# List of members that should be excluded from receiving reviews, and an
82-
# optional reason.
83-
excludedMembers:
84-
# GitHub login name (username).
85-
- login: aanm
86-
reason: Want to be part of team 'bpf' but will not be assigned to leave
87-
reviews.
88-
# The number of team members to assign.
89-
teamMemberCount: 1
91+
id: T_kwDOAUFEZs4Ah5D3
92+
# team restID, retrieved from GitHub
93+
restID: 8884471
94+
# Team's description
95+
description: Teams and sigs used for Cilium projects
96+
# Team's privacy settings. Valid values: VISIBLE|SECRET
97+
privacy: VISIBLE
98+
# Teams that are children of this parent team
99+
children:
100+
# Team Name
101+
ebpf:
102+
# team ID, retrieved from GitHub
103+
id: MDQ6VGVhbTQ5MjY2ODE=
104+
# team restID, retrieved from GitHub
105+
restID: 4926681
106+
# Team's description
107+
description: All code related with ebpf.
108+
# List of members' logins that belong to this team.
109+
members:
110+
- aanm
111+
- borkmann
112+
- joestringer
113+
codeReviewAssignment:
114+
# algorithm, currently can be LOAD_BALANCE or ROUND_ROBIN.
115+
algorithm: LOAD_BALANCE
116+
# set 'true' if codeReviewAssignment should be enabled.
117+
enabled: true
118+
# Notify the entire team of the PR if it is delegated.
119+
notifyTeam: false
120+
# List of members that should be excluded from receiving reviews, and
121+
# an optional reason.
122+
excludedMembers:
123+
# GitHub login name (username).
124+
- login: aanm
125+
reason: Want to be part of team 'bpf' but will not be assigned to leave
126+
reviews.
127+
# The number of team members to assign.
128+
teamMemberCount: 1
129+
# Team's privacy settings. Valid values: VISIBLE|SECRET
130+
privacy: VISIBLE
131+
# Team Name
90132
policy:
91133
id: MDQ6VGVhbTI1MTk3ODY=
134+
restID: 8884472
135+
description: All control plane code related with Policy
92136
members:
93137
- aanm
94138
- joestringer
@@ -97,6 +141,7 @@ teams:
97141
enabled: true
98142
notifyTeam: true
99143
teamMemberCount: 1
144+
privacy: SECRET
100145
# List of members that should be excluded from review assignments for the teams
101146
# that they belong. This list can exist for numerous reasons, person is
102147
# currently PTO or busy with other work.
@@ -107,7 +152,7 @@ excludeCodeReviewAssignmentFromAllTeams:
107152
4. Once the changes stored in a local configuration file, run `./team-manager push --org cilium`:
108153

109154
```bash
110-
$ ./team-manager push --org cilium
155+
$ ./team-manager push --config-filename ./cilium-team-assignments.yaml
111156
Local config out of sync with upstream: Unified diff:
112157
--- local
113158
+++ remote
@@ -136,8 +181,30 @@ Excluding members from team: bpf
136181
Excluding members from team: policy
137182
```
138183

184+
# Repository and members sync
185+
186+
Starting with v1.0.0, team-manager has the ability to also sync repository and
187+
members permissions. Before changing the file locally to push new changes,
188+
it is important to always perform a 'sync':
189+
```bash
190+
$ ./team-manager sync --config-filename ./team-assignments.yaml
191+
```
192+
193+
Then, after modifying the file on `team-assignments.yaml`, push the changes:
194+
195+
```bash
196+
$ ./team-manager push --config-filename ./team-assignments.yaml
197+
```
198+
139199
# GitHub action
140200

201+
On a large GitHub organization, it might be difficult to control who can create
202+
repositories. Thus, when running team manager with a GitHub action, it should
203+
run with `--repositories=false` and `--members=false` otherwise the GitHub
204+
action might override repository permissions that were set from the web-ui
205+
and remove or add members to the organization that were previously added or
206+
removed from the web-ui.
207+
141208
```yaml
142209
name: Team management
143210
on:
@@ -152,11 +219,43 @@ jobs:
152219
runs-on: ubuntu-20.04
153220
steps:
154221
- uses: actions/checkout@v1
155-
- uses: docker://quay.io/cilium/team-manager:v0.0.1
222+
- uses: docker://quay.io/cilium/team-manager:v1.0.0
156223
name: Sync team
157224
with:
158225
entrypoint: team-manager
159-
args: push --force --config-filename ./team-assignments.yaml
226+
# With --repositories=false --members=false, it will have the same
227+
# behavior as <= v0.0.8.
228+
args: --force --repositories=false --members=false --config-filename ./team-assignments.yaml
160229
env:
161230
GITHUB_TOKEN: ${{ secrets.ADMIN_ORG_TOKEN }}
162-
```
231+
```
232+
233+
# Check number of reviewers
234+
235+
To disable code review assignments, the GitHub user can either set its status as
236+
'busy' or the team maintainer can exclude them from the list of reviewers.
237+
238+
Since the team maintainer can't control the status of the user, it is important
239+
to retrieve the list of teams that don't have enough reviewers, by checking
240+
which users have their status as 'busy' or the ones that are excluded from
241+
reviews.
242+
243+
```bash
244+
$ ./team-manager status --config-filename ./cilium-team-assignments.yaml
245+
Checking status of "aanm"
246+
Checking status of "joestringer"
247+
Checking status of "borkmann"
248+
Team "bpf" with 3 members doesn't have enough reviewers:
249+
- aanm - excluded
250+
- joestringer - busy
251+
- borkmann - ok
252+
```
253+
254+
# Upgrade from <=0.0.8 to 1.0.0
255+
256+
1. Use 'sync' to sync the upstream configuration with the local file. It will
257+
fetch the information from GitHub and merge it with the local file.
258+
259+
```bash
260+
$ ./team-manager sync --config-filename ./team-assignments.yaml
261+
```

‎cmd/teams.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import (
77
"context"
88
"fmt"
99

10-
gh "github.com/google/go-github/v33/github"
10+
gh "github.com/google/go-github/v57/github"
1111
"github.com/spf13/cobra"
1212

1313
"github.com/cilium/team-manager/pkg/config"

‎cmd/users.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import (
88
"fmt"
99
"strings"
1010

11-
gh "github.com/google/go-github/v33/github"
11+
gh "github.com/google/go-github/v57/github"
1212
"github.com/spf13/cobra"
1313

1414
"github.com/cilium/team-manager/pkg/config"

‎pkg/github/client.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import (
1919
"fmt"
2020
"os"
2121

22-
gh "github.com/google/go-github/v33/github"
22+
gh "github.com/google/go-github/v57/github"
2323
"github.com/shurcooL/githubv4"
2424
"golang.org/x/oauth2"
2525
)

‎pkg/team/manager.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import (
2020
"sort"
2121
"strings"
2222

23-
gh "github.com/google/go-github/v33/github"
23+
gh "github.com/google/go-github/v57/github"
2424
"github.com/schollz/progressbar/v3"
2525
"github.com/shurcooL/githubv4"
2626
"github.com/shurcooL/graphql"

‎pkg/team/push.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ import (
2626
"github.com/cilium/team-manager/pkg/github"
2727
"github.com/cilium/team-manager/pkg/slices"
2828
"github.com/cilium/team-manager/pkg/terminal"
29-
gh "github.com/google/go-github/v33/github"
29+
gh "github.com/google/go-github/v57/github"
3030
"github.com/shurcooL/githubv4"
3131
)
3232

‎team-assignments.yaml

+65-27
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
11
organization: cilium
2-
slackWorkspace: cilium.slack.com
3-
# List of members that belong to the organization, ordered by GitHub login (username).
2+
repositories:
3+
# Repository name
4+
cilium:
5+
# User-specific permissions. Always prefixed with 'USER'.
6+
# Valid options: 'USER-ADMIN', 'USER-MAINTAIN', 'USER-WRITE', 'USER-TRIAGE', 'USER-READ'
7+
USER-READ:
8+
- ciliumbot
9+
# Team-specific permissions.
10+
# Valid options: 'ADMIN', 'MAINTAIN', 'WRITE', 'TRIAGE', 'READ'
11+
WRITE:
12+
- bpf
13+
- sig-policy
414
members:
515
aanm:
616
# User ID, retrieved from GitHub
@@ -15,35 +25,62 @@ members:
1525
joestringer:
1626
id: MDQ6VXNlcjEyNDMzMzY=
1727
name: Joe Stringer
18-
# List of teams that belong to the organization, ordered by team names.
28+
# The list of 'outsideCollaborators' is automatically derived from the list of users that don't
29+
# belong to the organization but have access to at least one of the repositories
30+
# of the organization.
31+
outsideCollaborators:
32+
ciliumbot:
33+
reason: "Only has access to some repositories"
34+
# List of teams that belong to the organization.
1935
teams:
20-
bpf:
36+
# Team Name
37+
Cilium Teams:
2138
# team ID, retrieved from GitHub
22-
id: MDQ6VGVhbTI1MTk3Nzk=
23-
# List of members' logins that belong to this team.
24-
members:
25-
- aanm
26-
- borkmann
27-
- joestringer
28-
# codeReviewAssignment
29-
codeReviewAssignment:
30-
# algorithm, currently can be LOAD_BALANCE or ROUND_ROBIN.
31-
algorithm: LOAD_BALANCE
32-
# set 'true' if codeReviewAssignment should be enabled.
33-
enabled: true
34-
# Notify the entire team of the PR if it is delegated.
35-
notifyTeam: false
36-
# List of members that should be excluded from receiving reviews, and an
37-
# optional reason.
38-
excludedMembers:
39-
# GitHub login name (username).
40-
- login: aanm
41-
reason: Want to be part of team 'bpf' but will not be assigned to leave
42-
reviews.
43-
# The number of team members to assign.
44-
teamMemberCount: 1
39+
id: T_kwDOAUFEZs4Ah5D3
40+
# team restID, retrieved from GitHub
41+
restID: 8884471
42+
# Team's description
43+
description: Teams and sigs used for Cilium projects
44+
# Team's privacy settings. Valid values: VISIBLE|SECRET
45+
privacy: VISIBLE
46+
# Teams that are children of this parent team
47+
children:
48+
# Team Name
49+
ebpf:
50+
# team ID, retrieved from GitHub
51+
id: MDQ6VGVhbTQ5MjY2ODE=
52+
# team restID, retrieved from GitHub
53+
restID: 4926681
54+
# Team's description
55+
description: All code related with ebpf.
56+
# List of members' logins that belong to this team.
57+
members:
58+
- aanm
59+
- borkmann
60+
- joestringer
61+
codeReviewAssignment:
62+
# algorithm, currently can be LOAD_BALANCE or ROUND_ROBIN.
63+
algorithm: LOAD_BALANCE
64+
# set 'true' if codeReviewAssignment should be enabled.
65+
enabled: true
66+
# Notify the entire team of the PR if it is delegated.
67+
notifyTeam: false
68+
# List of members that should be excluded from receiving reviews, and
69+
# an optional reason.
70+
excludedMembers:
71+
# GitHub login name (username).
72+
- login: aanm
73+
reason: Want to be part of team 'bpf' but will not be assigned to leave
74+
reviews.
75+
# The number of team members to assign.
76+
teamMemberCount: 1
77+
# Team's privacy settings. Valid values: VISIBLE|SECRET
78+
privacy: VISIBLE
79+
# Team Name
4580
policy:
4681
id: MDQ6VGVhbTI1MTk3ODY=
82+
restID: 8884472
83+
description: All control plane code related with Policy
4784
members:
4885
- aanm
4986
- joestringer
@@ -52,6 +89,7 @@ teams:
5289
enabled: true
5390
notifyTeam: true
5491
teamMemberCount: 1
92+
privacy: SECRET
5593
# List of members that should be excluded from review assignments for the teams
5694
# that they belong. This list can exist for numerous reasons, person is
5795
# currently PTO or busy with other work.

0 commit comments

Comments
 (0)