Teams

Overview

A team is a named set of people in your organisation — Backend, SRE, Security reviewers. A team can do nothing by itself. You give it access the way you give a person access, with a grant on a group or repository, and everyone on the team has that access for as long as they are on it.

That is what makes teams worth having: the roster and the access are kept apart. When someone joins Backend, you add them to the team once, and they can do everything Backend can do everywhere. When they leave, you take them off once. Nobody has to find and change each group and repository by hand.

Quick start

Before you start

How it works

A team has people, and grants. Its people are the roster. Its grants are made through access, exactly as for a person, and say what the team can do and where. Everyone on the roster has every one of the team's grants.

Only people join teams. A service account cannot be put on a team — every place a team is named, such as an approver list or a code owner, is a place a bot silently joining would be a surprise. Give a service account access directly instead.

Joining a team is being given its access, and is checked that way. You can put someone on a team only if you could have given them each of the team's grants yourself. A maintainer who is a Developer on a repository cannot add someone to a team that is Owner of it; an Owner there can. The same check applies when you make someone a maintainer, or let their place run longer. Taking someone off a team, making a maintainer a member, or ending their place sooner gives nobody anything, and is never refused for this reason.

A refusal says what you lack, where you can see it. If the team holds access somewhere you cannot see, the refusal says so without naming the place.

Places can end on their own. Give someone an end date, up to a year away, and the team's access stops reaching them then, with nothing to remember to undo.

A team can follow a group in your identity provider. Link it to the group's name, and each time someone signs in through single sign-on, their place on the team follows what your provider says: they are put on it when the group is in their sign-in, and taken off when it is not. A place your provider confirms lasts for the connection's sync period — 30 days unless you change it — so someone who stops signing in drops off on their own. Linking makes the people already on the team subject to the same rule — an end date you set by hand that comes sooner stays. Groups are read only for accounts linked to your organisation's own provider, and only your provider can set them, so nobody can put themselves on a linked team. While a team is linked, nobody changes its people by hand, and nobody can leave it except through your provider. If your organisation provisions over SCIM, sign-in sync is off: linked teams stop following sign-ins, and their places lapse at the end of the sync period.

A team your provider keeps over SCIM is your provider's too. It is one of your provider's groups, pushed as it changes: people are put on it and taken off it as your provider says, not at sign-in, and their places do not lapse. As with a linked team, nobody changes its people by hand, and it cannot be linked to a group in the sign-in instead: its roster is your provider's, over SCIM.

Deleting a team takes its access with it. Every grant the team holds is revoked, and everyone on it loses what the team gave them. What they hold in their own right is untouched. Preview a deletion first to see how far the team's access reaches.

Every change is recorded. Creating and deleting a team, and every change to its roster made by a person or pushed over SCIM, lands in the organisation's audit log. The places a sign-in adds to or removes from a linked team are not recorded there one by one.

How to

Create a team

Name it with a slug — lowercase letters, digits and hyphens, unique in the organisation — and a display name. You can list its first people in the same request; you become a maintainer unless you list yourself otherwise.

See an organisation's teams

Narrow the list with search, a fragment of a team's slug or name.

Put someone on a team, or change their place

Choose member or maintainer, and optionally when their place ends. Putting someone on a team they are already on replaces their place with the one you send, so leaving out the end date makes it last until they are taken off.

Add dry_run=true — --dry-run in the CLI — to see what they would gain, and change nothing. The answer counts the team's grants, how many of the groups and repositories they reach you can see, and whether there are others.

See who is on a team

See what a team can do

Every grant the team holds on a group or repository you can see, with the role and when it ends. If the team holds access somewhere you cannot see, hidden_scopes says so.

See where a team is used

A team can be more than access. It can be named as approvers on an approval rule or a protected environment, be allowed to push or merge on a protected branch, own a service, or own code through a line of a repository's CODEOWNERS file (@your-org:release). Before you add someone to a team, look here: they will be asked for approvals, be able to approve deployments, own what the team owns, and be a required reviewer of that code.

Each place is listed only if you can see it there, and hidden says whether the team is named anywhere else. Each list holds at most 100 places; truncated says when one stops short.

CODEOWNERS lines are read from each repository's default branch the next time something is pushed or merged there, so a repository nobody has pushed to since this list existed does not show its lines yet. A line that names the team by an old name is not listed — it no longer makes anyone a reviewer either, so fix the line.

Take someone off a team, or leave one

A maintainer, or an Owner of the organisation, can take anyone off. Anyone can leave a team themselves — except a team your identity provider keeps, which you leave by leaving the group there.

Keep a team's roster in your identity provider

Name the group exactly as your provider sends it in the sign-in, capital letters included — Engineering, not its id, unless your provider sends ids. Your single sign-on connection has to map a groups claim first (attribute_mapping.groups), or no sign-in would ever say who is in the group. Linking needs the right to manage the organisation's teams, and — because everyone the provider puts in the group gets the team's access — you must be able to give each of the team's grants yourself. From the moment you link it, everyone already on the team has one sync period to be confirmed by a sign-in before their place lapses.

Keep a team's roster by hand again

Unlinking leaves everyone your provider last confirmed on the team, and their places stop lapsing. A place that had already lapsed is removed, so nobody whose place ran out comes back. An end date you set by hand before you linked the team stays; the ones the sync set go. Unlinking a team kept by hand changes nothing. A team your provider keeps over SCIM cannot be unlinked — it was never linked.

Rename a team, or change its description

Renaming needs an Owner of the organisation. A team's maintainers can change its description.

Delete a team

See your own teams

Every team you are on, in every organisation, with your place on each.

Reference

Limits

Teams per organisation — 10 on the Free plan. People per team — 50 on the Free plan.

At either limit the request is refused with 429 TOO_MANY_REQUESTS and nothing is written. Delete teams that are no longer used, or raise the limit: a higher plan lifts both, and an Owner can ask for a higher limit on one namespace.

A team holds at most 500 grants. Giving a team access beyond that is refused with 429; give it access on a group higher up instead, which reaches everything beneath.

An end date can be at most a year away.

Troubleshooting

Examples

Give a whole team access to one area

Check what adding someone would give them, before doing it

List everyone on a team

FAQ

Related