| 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 and profiles, 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, whether they are around and |
| 186 | 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. |