flagon-io/g1t

public

1	---
2	title: Teams
3	description: Group a workspace's people and agents into teams, give a team a lead, a channel and a budget for its agents, give a team a role on repositories, mention it with @workspace/team, and ask it to review pull requests, with review assignment picking who.
4	---
5
6	A team is a group of a workspace's people and agents, in any mix:
7	people and agents together, people only, or agents only. Instead of
8	giving each person a role on each repository, you give the team a role,
9	and everyone in it has it. A team can have a lead, a channel and a
10	monthly budget for its agents, and every agent on it is told who is on
11	the team, who leads it and who owns what. A team is also a name you can use in conversation: mention
12	`@acme/backend` in a comment and everyone in it hears of it, or ask it to
13	review a pull request and it decides who looks.
14
15	Only members of a workspace, and its own agents, can be in its teams.
16	Someone who leaves the workspace leaves all of its teams with it.
17
18	For the workspace's directory, profiles and org chart, see
19	[people and teams](/guides/people-and-teams/).
20
21	## Create a team
22
23	Any member of the workspace with a confirmed email address can create a
24	team, and becomes its first maintainer, unless an owner has set
25	[who can create teams](#who-can-create-teams) to owners only.
26
27	1. Open Teams in the sidebar: `g1t.sh/<workspace>/-/teams`.
28	2. Choose New team, or go to `g1t.sh/<workspace>/-/teams/new`. The
29	+ menu in the top bar has New team too, for the workspace the
30	sidebar is on.
31	3. Give it a name, such as `Backend`. Its slug, the name used in
32	addresses and mentions, is made from the name (`backend`); you can
33	change it.
34	4. Optionally, add a description, choose its visibility, pick a
35	parent team, and add members.
36	5. Choose Create team.
37
38	The team's page is `g1t.sh/<workspace>/-/teams/<team>`, and it is
39	mentioned as `@<workspace>/<team>`.
40
41	\| Field \| Limits \|
42	\| --- \| --- \|
43	\| Name \| Up to 80 characters. \|
44	\| Slug \| 1 to 60 lowercase letters, digits and single hyphens, not starting or ending with a hyphen. Unique in the workspace. `Web & Mobile` becomes `web-mobile`. \|
45	\| Description \| Up to 280 characters. \|
46	\| Teams in one workspace \| Up to 500. \|
47
48	The Teams page lists the teams you can see, yours first, then by
49	name, with a search box that matches names and slugs. Each team shows a
50	small mark for what it is made of, and counts such as
51	2 members · 1 agent · 1 repository. A person's teams also show on
52	their card in the [People directory](/guides/people-and-teams/#the-directory)
53	and on their profile.
54
55	### Who can create teams
56
57	An owner chooses who can create the workspace's teams, under **Workspace →
58	Access → [Permissions](/guides/permissions/#people-and-teams)**, in the
59	People and teams card:
60
61	\| Who can create teams \| \|
62	\| --- \| --- \|
63	\| Any member \| Every member with a confirmed email address. The default. \|
64	\| Owners only \| Only the workspace's owners. Members see Only owners can create teams in this workspace. on the Teams page instead of New team, and New team in the + menu is greyed out. \|
65
66	Teams that already exist stay as they are, and their maintainers still
67	manage them. The change is recorded in the [audit log](/guides/audit-log/)
68	as `workspace.team_creation_changed`.
69
70	Through the API, set `team_creation` to `members` or `owners` with
71	[`PATCH /workspaces/{workspace}`](/reference/api/workspaces/update-workspace/)
72	(the `workspace` tool's `update` action over MCP); the workspace you get
73	back, and [`GET /workspaces/{workspace}`](/reference/api/workspaces/get-workspace/),
74	include it. Creating a team when you may not is refused with `403`.
75
76	## Visibility
77
78	\| Visibility \| Who can see it, mention it and ask it to review \|
79	\| --- \| --- \|
80	\| Visible \| Every member of the workspace. The default. \|
81	\| Secret \| Its own people and the workspace's owners. To anyone else it does not exist. \|
82
83	Secret teams cannot be nested: a secret team has no parent and no child
84	teams. To make a nested team secret, first take it out from under its
85	parent and move its child teams elsewhere.
86
87	## Maintainers and members
88
89	Each person in a team is a maintainer or a member. Maintainers
90	look after the team; owners of the workspace can do everything a
91	maintainer can on every team, whether or not they are in it.
92
93	\| \| Who \|
94	\| --- \| --- \|
95	\| See a visible team \| Every member of the workspace \|
96	\| See a secret team \| Its own people and the workspace's owners \|
97	\| Create a team \| Any member. Under a parent: an owner, or a maintainer of the parent \|
98	\| Add and remove people, make someone a maintainer \| Owners, and the team's maintainers \|
99	\| Add and remove agents \| Owners, and the team's maintainers \|
100	\| Set its lead, channel and budget \| Owners, and the team's maintainers \|
101	\| Change its name, slug, description, visibility, notifications and review assignment \| Owners, and the team's maintainers \|
102	\| Move it under another team \| Owners, or someone who maintains both teams \|
103	\| Delete it \| Owners, and the team's maintainers \|
104	\| Give it a role on a repository \| Anyone with the Admin [role](/guides/access-and-roles/) on that repository \|
105	\| Take its role on a repository away \| Admin on that repository, owners, and the team's maintainers \|
106	\| Leave it \| Anyone in it \|
107
108	Changing a team is for people, signed in or with a personal access token,
109	with a confirmed email address. An agent's token or a workspace's token
110	cannot change one.
111
112	To manage the people in a team:
113
114	1. Open the team, `g1t.sh/<workspace>/-/teams/<team>`. **People and
115	agents** is its first tab.
116	2. Add someone by username. They must already be a member of the
117	workspace.
118	3. Beside a person, choose Make maintainer (or Make member), or
119	Remove. Beside yourself, Leave.
120
121	Turn on Include the people of child teams to also list the people of its
122	[child teams](#nesting), each with the child team they are in.
123
124	## Agents on a team
125
126	The People and agents tab lists the team's Agents under its
127	people. An agent is on a team exactly as a person is: a maintainer or an
128	owner adds it, and it stays until one of them takes it off. Nothing on the
129	agent itself names a team, and an agent can be on any number of teams.
130
131	To add or remove an agent:
132
133	1. Open the team's People and agents tab,
134	`g1t.sh/<workspace>/-/teams/<team>`.
135	2. Under Agents, choose one of the workspace's agents in **Add an
136	agent, and Add**.
137	3. To take an agent off, choose Remove beside it.
138
139	You can do the same from the agent's side: under Teams on its
140	Profile tab in [Agents](/guides/agents/#teams), and under **Add to
141	teams** when you make it. A personal agent is on no team. Agents are not
142	in the [People directory](/guides/people-and-teams/#the-directory); a
143	team's page is where they are listed beside people.
144
145	An agent on a team works with the access of whoever asks it, not with the
146	team's roles on repositories. Being on a team tells the agent about it
147	(see [what agents on the team know](#what-agents-on-the-team-know)), and
148	its spend counts towards the team's [budget](#lead-channel-and-budget).
149
150	## Lead, channel and budget
151
152	A team's header shows what it is made of (such as People only, *Agents
153	only, or 2 people and 1 agent), Led by, its #channel*,
154	Code: N repositories (its roles on repositories), Storage
155	(coming), and its budget: $X of $Y this month, what its agents spent
156	together against it.
157
158	A maintainer or an owner sets them under the team's Settings, **Lead,
159	channel and budget**:
160
161	\| Setting \| What it is \|
162	\| --- \| --- \|
163	\| Lead \| Someone on the team: a person or an agent. Choosing one of the workspace's agents that isn't on the team adds it to the team too. When a person is needed, the team's agents ask the lead first. \|
164	\| Channel \| The team's channel in [Chat](/guides/chat/), by name. Leave it empty for none. \|
165	\| Budget for its agents, a month \| In dollars, such as `150`. Empty or `0` for no team budget. At most $1,000,000. \|
166	\| Storage level \| Coming. \|
167
168	Taking the lead off the team, or out of the workspace, leaves the team
169	with no lead.
170
171	The budget caps what the agents on the team spend together in a calendar month (UTC). When they reach it, its agents
172	take no new work until the 1st, and say:
173
174	```text
175	Backend's agents have used the team's budget of $150.00 for this month. Someone who manages the team can raise it on its settings.
176	```
177
178	Each agent keeps its own budget too; the first limit reached stops the
179	work. See [how limits stack](/guides/agent-budgets/#how-limits-stack).
180
181	## What agents on the team know
182
183	Every agent on a visible team is told about it every time it replies and
184	at every session step: its description, lead, channel and budget, each
185	person with their title, what they own, who they report to, whether they
186	are around and their local time, and the team's other agents. The
187	People and agents tab shows the team's part of it, exactly as the
188	agents get it, under What the agents on team know about it.
189
190	Agents are never told about secret teams. See
191	[what agents are told](/guides/people-and-teams/#what-agents-are-told).
192
193	## Nesting
194
195	A team can have a parent. Choose one when you create it, or under the
196	team's Settings. A child team:
197
198	- inherits its parent's roles on repositories, and its parent's
199	parent's, all the way up. Its own role on a repository counts too; the
200	highest wins.
201	- is reached by its parent's mentions and review requests. Mentioning
202	`@acme/engineering` tells the people of `@acme/backend` under it too, and
203	asking `@acme/engineering` to review asks them too.
204
205	It never works the other way: a team's own people get nothing from its
206	child teams.
207
208	\| Rule \| \|
209	\| --- \| --- \|
210	\| How deep \| At most 8 levels: a team, its child, that child's child, and so on. \|
211	\| Secret teams \| Cannot have a parent or child teams. \|
212	\| Cycles \| A team cannot go under itself or one of its own child teams. \|
213	\| Deleting a parent \| Its child teams move up to its own parent, or to the top if it had none. \|
214
215	The Child teams tab, `g1t.sh/<workspace>/-/teams/<team>/teams`, lists
216	a team's children. To take a team out from under its parent, clear
217	Parent in its settings.
218
219	## Repository access
220
221	A team is given a role on a repository the way a person is, with the
222	same five [roles](/guides/access-and-roles/#the-roles). Everyone in the
223	team, and in its child teams, has that role there. A team has roles only on
224	its own workspace's repositories.
225
226	From the team:
227
228	1. Open the team's Repositories tab,
229	`g1t.sh/<workspace>/-/teams/<team>/repositories`.
230	2. Choose a repository and a role, and Add.
231
232	Or from the repository: someone with Admin opens Settings → Access,
233	`g1t.sh/<workspace>/<repo>/settings/access`, and adds the team, with a role,
234	under Teams with access.
235
236	The Repositories tab lists the team's own roles and the ones it
237	inherits, each repository once at the highest role, naming the parent team
238	an inherited one comes from. Change a role by picking another, or
239	Remove it. A role a team inherits can only be changed on the parent
240	that gives it.
241
242	### How roles combine
243
244	Your role on a repository is the highest of everything that gives you one:
245	ownership, the base permission, roles given to you directly, and the roles
246	of every team you are in and of their parents. See
247	[how your role is worked out](/guides/access-and-roles/#how-your-role-is-worked-out).
248
249	For example, in a workspace whose base permission is Read:
250
251	\| Where it comes from \| Role on `acme/api` \|
252	\| --- \| --- \|
253	\| Base permission \| Read \|
254	\| `@acme/engineering`, a parent of `@acme/backend` \| Write \|
255	\| `@acme/backend`, which Ana is in \| Maintain \|
256	\| Given to Ana directly \| Triage \|
257	\| Ana's role \| Maintain, from `@acme/backend` \|
258
259	The repository's Settings → Access lists Teams with access, each
260	with its role and how many people are in it, and shows for each person
261	where their role comes from, such as Through team backend. When two give
262	the same role, a role given directly is shown first, then a team's, so the
263	one shown is the one you would change.
264
265	Taking someone's direct role away leaves what their teams give them. To
266	take away what a team gives, remove the team's role, or remove the person
267	from the team.
268
269	## Mentions
270
271	Write `@<workspace>/<team>`, such as `@acme/backend`, in a comment, or in
272	the description of an issue or pull request when you open it, and the
273	people of that team and its child teams are told in their
274	[notifications](/guides/notifications/), with the reason `team_mention`:
275
276	```text
277	ana mentioned @acme/backend on acme/api#42
278	```
279
280	Comment boxes suggest teams as you type `@acme/`.
281
282	\| \| \|
283	\| --- \| --- \|
284	\| Who is told \| Everyone in the team and its child teams, but not whoever wrote it. \|
285	\| When \| The team's Notify the team when it is mentioned setting is on (the default), and the writer can see the team: a member of its workspace, and for a secret team, in it or an owner. Otherwise nobody is told. \|
286	\| Not a mention \| `@acme/backend` in code, in a quoted line (`>`), inside an address or a path such as `ops@acme/backend` or `@acme/backend/src`, or in a package name such as `@acme/backend@1`. \|
287	\| Subscribes them \| Yes. Each person told is subscribed to the issue or pull request, as with a mention by name. \|
288
289	Someone mentioned by name and through a team is told once, as `mention`.
290	People only see what is about repositories they can read.
291
292	To stop a team's mentions telling its people, a maintainer turns off
293	Notify the team when it is mentioned in the team's Settings. The team can still be
294	mentioned; the text links to it, and nobody is told.
295
296	## Review requests
297
298	A pull request can ask a team to review it. Add the team in the
299	Reviewers box on the pull request, as `@acme/backend`, or have a
300	[CODEOWNERS file](/guides/codeowners/) ask it. Asking needs what asking a
301	person needs: the Triage role or higher, or being the pull request's
302	author.
303
304	- Only teams of the repository's own workspace can be asked.
305	- A secret team can be asked only by its own people and owners.
306	- A pull request can ask up to 10 teams.
307
308	The team stays listed under Reviewers as requested. What happens next
309	depends on its review assignment:
310
311	\| Review assignment \| Who is asked \|
312	\| --- \| --- \|
313	\| Off (the default) \| Everyone in the team and its child teams is told, with the reason `review_requested`, never the pull request's author. Anyone in it can review. \|
314	\| On \| g1t picks people from the team. Each one picked becomes a reviewer in their own right, listed under Reviewers beside the team, and is told. \|
315
316	Removing a team from Reviewers takes the request away; people it
317	picked stay reviewers until you remove them too.
318
319	### Review assignment
320
321	A maintainer sets it in the team's Settings, under **Code review
322	assignment**:
323
324	\| Setting \| Default \| What it does \|
325	\| --- \| --- \| --- \|
326	\| Assign reviewers from the team \| Off \| On: pick people instead of asking the whole team. \|
327	\| How many people \| 1 \| People to pick, 1 to 10. People from the team who are already reviewers count towards it. \|
328	\| Who goes first \| Round robin \| Round robin or Load balance. See below. \|
329	\| Skip people who are busy \| Off \| Leave out anyone with too many pull requests waiting on their review. Beside it, how many waiting pull requests makes someone busy, 1 to 100 (5 by default). \|
330	\| Pick from child teams too \| Off \| Also pick from the people of its child teams. \|
331	\| Also tell the rest of the team \| Off \| Also tell everyone else in the team when people are picked. \|
332	\| Never pick \| None \| Usernames never picked, up to 100. \|
333
334	A pull request is waiting on someone when it is open or a draft, they
335	are one of its reviewers, and they have not yet approved it or asked for
336	changes.
337
338	g1t never picks the pull request's author (or, for a change g1t made, the
339	person who asked for it), g1t itself, anyone under Never pick, or
340	anyone already asked. The same facts always pick the same people: ties go
341	by username.
342
343	\| Algorithm \| Who goes first \|
344	\| --- \| --- \|
345	\| Round robin \| Whoever this team has had asked least recently. People it has never asked come first of all. Everyone is asked once before anyone is asked twice. \|
346	\| Load balance \| Whoever has the fewest pull requests waiting on their review. Among equals, whoever this team asked least recently. \|
347
348	For example, `@acme/backend` has five people:
349
350	\| Person \| Last asked by the team \| Waiting on them \|
351	\| --- \| --- \| --- \|
352	\| ana \| 5 October \| 1 \|
353	\| bo \| never \| 4 \|
354	\| cy \| 1 October \| 0 \|
355	\| dee \| 6 October \| 0 \|
356	\| eve \| never \| 2 \|
357
358	zed opens a pull request and asks `@acme/backend` to review it:
359
360	\| Settings \| Picked \|
361	\| --- \| --- \|
362	\| Round robin, how many 1 \| bo (never asked; first by name) \|
363	\| Round robin, how many 3 \| bo, eve, cy \|
364	\| Load balance, how many 2 \| cy, dee (nothing waiting; cy asked longer ago) \|
365	\| Round robin, how many 3, skip busy at 2 \| cy, ana, dee (bo and eve are busy) \|
366	\| Round robin, how many 2, bo already a reviewer \| eve (bo counts towards the 2) \|
367	\| Round robin, how many 3, opened by bo \| eve, cy, ana (never the author) \|
368
369	### On the pull request
370
371	The timeline records who asked whom: **ana requested a review from
372	@acme/backend, and, when people are picked, requested a review from
373	cy. Notifications say ana asked @acme/backend to review acme/api#42** to
374	the team's people, and ana asked you to review acme/api#42 to each
375	person picked. A request made by a CODEOWNERS file reads **acme/api#42
376	changes files @acme/backend owns**.
377
378	## Settings
379
380	A team's Settings, `g1t.sh/<workspace>/-/teams/<team>/settings`, holds
381	its name, slug, description, visibility, parent, **Lead, channel and
382	budget, Notify the team when it is mentioned, Code review
383	assignment, and Delete team**.
384
385	Changing the slug changes how the team is mentioned and its address. A
386	CODEOWNERS file that names the old slug no longer resolves it, and shows an
387	error until you change the file.
388
389	Deleting a team takes away every role it gave on repositories, and its
390	child teams move up to its parent. Its people stay in the workspace.
391
392	## Through the API
393
394	Every route is in the [API reference](/reference/api/), and each is an
395	action of the `team` [MCP tool](/reference/mcp/). Reading teams needs the
396	`workspace:read` scope; changing them `workspace:admin`; giving or taking
397	a team's role on a repository `access:admin`.
398
399	\| Route \| MCP action \| What it does \|
400	\| --- \| --- \| --- \|
401	\| `GET /workspaces/{workspace}/teams` \| `list` \| The teams you can see, yours first. `q` narrows by name or slug. \|
402	\| `POST /workspaces/{workspace}/teams` \| `create` \| Create a team. Body: `name`, and optionally `slug`, `description`, `visibility` (`visible` or `secret`), `parent` (a slug), `notify` and `members` (usernames). \|
403	\| `GET /workspaces/{workspace}/teams/{team}` \| `get` \| One team. \|
404	\| `PATCH /workspaces/{workspace}/teams/{team}` \| `update` \| Change what you give: `name`, `slug`, `description`, `visibility`, `parent` (`""` takes it out from under its parent), `notify`, `review_assignment`. \|
405	\| `DELETE /workspaces/{workspace}/teams/{team}` \| `delete` \| Delete a team. \|
406	\| `GET /workspaces/{workspace}/teams/{team}/members` \| `list_members` \| Its people. `include_child_teams=true` adds its child teams' people, each with `via`. \|
407	\| `PUT /workspaces/{workspace}/teams/{team}/members/{username}` \| `set_member` \| Add someone, or change their place. Body: `role`, `member` or `maintainer`. \|
408	\| `DELETE /workspaces/{workspace}/teams/{team}/members/{username}` \| `remove_member` \| Take someone out, or leave. \|
409	\| `GET /workspaces/{workspace}/teams/{team}/teams` \| `list_child_teams` \| Its child teams. \|
410	\| `GET /workspaces/{workspace}/teams/{team}/repos` \| `list_repos` \| The repositories it has a role on, its own and inherited (`inherited_from`). \|
411	\| `PUT /workspaces/{workspace}/teams/{team}/repos/{repo}` \| `set_repo` \| Give it a role on a repository, or change it. Body: `role`. \|
412	\| `DELETE /workspaces/{workspace}/teams/{team}/repos/{repo}` \| `remove_repo` \| Take its role away. \|
413	\| `PUT /workspaces/{workspace}/teams/{team}/review_assignment` \| `set_review_assignment` \| Set review assignment: `enabled`, `algorithm` (`round_robin` or `load_balance`), `count`, `skip_busy`, `busy_at`, `include_child_teams`, `excluded`, `notify_team`. \|
414	\| `GET /workspaces/{workspace}/members/{username}/teams` \| `list_user_teams` \| The teams someone is in, as you can see them. \|
415
416	Asking a team to review is on the pull request: `POST
417	/repos/{owner}/{name}/pulls/{number}/requested_reviewers` with
418	`team_reviewers` (each as `workspace/team`, or the team's slug), and
419	`DELETE` on the same route to take a request away
420	(the `pull_request` tool's `request_reviewers` and
421	`remove_requested_reviewers` actions, with the `pull_requests:write`
422	scope). A pull request's `team_reviewers` lists the teams asked, as
423	`workspace/team`.
424
425	```sh
426	curl -X POST https://api.g1t.sh/workspaces/acme/teams \
427	-H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
428	-d '{"name": "Backend", "parent": "engineering", "members": ["ana", "cy"]}'
429	```
430
431	```json
432	{
433	"id": "team_01m4a3k0q6e8pd9h2x7c5vbn1r",
434	"workspace": "acme",
435	"slug": "backend",
436	"name": "Backend",
437	"description": null,
438	"visibility": "visible",
439	"parent": { "slug": "engineering", "name": "Engineering" },
440	"notify": true,
441	"review_assignment": {
442	"enabled": false,
443	"algorithm": "round_robin",
444	"count": 1,
445	"skip_busy": false,
446	"busy_at": 5,
447	"include_child_teams": false,
448	"excluded": [],
449	"notify_team": false
450	},
451	"members_count": 3,
452	"repos_count": 0,
453	"child_teams_count": 0,
454	"viewer_role": "maintainer",
455	"can_manage": true,
456	"created_at": "2026-10-07T15:04:11.208Z",
457	"updated_at": "2026-10-07T15:04:11.208Z"
458	}
459	```
460
461	```sh
462	curl -X PUT https://api.g1t.sh/workspaces/acme/teams/backend/repos/api \
463	-H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
464	-d '{"role": "maintain"}'
465	```
466
467	## Webhooks and the audit log
468
469	Changes to a team are sent to the workspace's [webhooks](/guides/webhooks/).
470	The `team.repo_*` events are about a repository, so that repository's
471	webhooks get them too.
472
473	\| Event \| When \|
474	\| --- \| --- \|
475	\| `team.created`, `team.edited`, `team.deleted` \| A team was created, changed or deleted. On `team.edited`, `data.changes` names what changed, such as `name` or `parent`. \|
476	\| `team.member_added`, `team.member_role_changed`, `team.member_removed` \| Someone joined or left a team, or became a maintainer or a member. `data.username`, `data.role`, `data.previous_role`. \|
477	\| `team.repo_added`, `team.repo_role_changed`, `team.repo_removed` \| A team was given a role on a repository, had it changed, or lost it. `data.repo`, `data.repo_id`, `data.repo_role`, `data.previous_repo_role`. \|
478
479	Each has `data.workspace`, `data.team_id`, `data.team` (its slug),
480	`data.name`, `data.visibility` and, for a child team, `data.parent`.
481
482	The workspace's [audit log](/guides/audit-log/) records the same changes
483	under the same names.