Access

Overview

Access is who can do what on a group or a repository. You give it with a grant: one person, service account or team, one role, one group or repository. What the role allows applies there and in everything beneath it, so giving someone Developer on a group lets them push to every repository inside it.

Four questions come up again and again, and each has one call: who has access here, and why; why can this person do this, or not; give these people this role here; and take it away. Each change can be previewed first, so you see exactly who gains or loses what before anything moves.

Quick start

Before you start

How it works

A grant is who, what and where. The who is a person, a service account or a team. The what is a role — one of the five built-in roles, Guest, Reporter, Developer, Maintainer and Owner, each holding everything the one below it holds, or a role your organisation defined. The where is a group or a repository. One subject holds at most one grant on one place; changing their role changes that grant.

Access flows down. A grant on a group reaches every subgroup and repository beneath it. Someone's access to a repository is everything their grants on it and on each group above it add up to — the highest role wins. A group or repository can stop access flowing into it from above; then only grants made on it, or beneath it, reach it, and the organisation's Owners always do.

The organisation's Owners always keep their access. Owner of the top-level group reaches everything in the organisation, whatever any group or repository beneath says. There is always at least one: the last Owner of an organisation cannot be removed or demoted until someone else is made one. Repositories and subgroups may be left without an Owner of their own, because the organisation's Owners manage them.

Visibility is separate from access. A public repository lets anyone read what it publishes — its code, its issues, its releases — and an internal one lets anyone signed in do the same. Visibility never lets anyone change anything, and never shows who has access.

Service accounts are kept close to home. An account holds access only in the group or repository it belongs to, or beneath it, and never as Owner. Its own level is changed on the account itself, not here.

Nobody gives what they do not hold. Every change is checked against your own access where the change is made: you can give or take away a role only if you hold everything it allows and it does not outrank you.

Every change is recorded. Giving, changing and revoking access each land in the organisation's audit log with the role before and after, not just the fact that something changed. A preview changes nothing, so it is not recorded.

How to

See who has access, and why

The list shows every grant that reaches the group or repository — made there, or inherited from a group above — oldest first, each with where it was made, who made it, why, and when it ends. The organisation's Owners are counted separately, because they reach everything anyway.

Narrow the list with source (direct or inherited), subject_kind (user, service_account or team) or search.

Find out why someone can or cannot do something

Ask about yourself, or — with Reporter there — about anyone. The answer lists every grant that bears on them, how it reaches them (directly, or through which team), whether it still counts, and what any limit took away. Name one permission, such as code.push, to get a plain yes or no as well.

Give access to people, service accounts or teams

Name up to 50 subjects and one role. They are all given access together, or none of them is. Someone who already has that exact role there is left as they are and listed as unchanged; someone who has a different role there is refused — change their existing grant instead.

Add expires_at for access that ends on its own, up to a year away, and reason so the next person reading the list knows why it exists.

Preview a change before making it

Add dry_run=true — --dry-run in the CLI — to giving, changing or revoking access. Nothing is written. The answer lists each person whose access would change where the change is made, with the permissions they would gain and lose and their role before and after, and counts how many groups and repositories the change reaches because they inherit from there. For a team, each member is listed.

Change someone's role, or when their access ends

Change the role, the end date or the reason of one grant, by its id from the list. Clearing the end date makes the access last until it is revoked. You need to be able to give both the role they have and the role you are giving them.

Revoke access, or give up your own

Revoking a grant takes effect on the next request; the history of what they did stays exactly where it is. Anyone can give up a grant they hold themselves.

Ask the three questions from the terminal

Three commands take a path instead of an id, and answer the questions people ask most:

• gitmoap access why acme/platform/api --user alice --permission code.push — whether Alice can push, and every grant, limit and boundary behind the answer. --user takes a username, an email address or an id; leave it out to ask about yourself.
• gitmoap access who acme/platform/api — who can reach it, their role, where each grant was made and when it ends, up to a thousand entries. Narrow it with --search.
• gitmoap access grant acme/platform/api alice bob team:<team-id> --role developer --expires 90d --reason "Billing rewrite" — give a role to people by username or email, to teams, or to service accounts (sa:<id>). --role takes a built-in role or role:<role-id> for one your organisation defined; --expires takes a number of days or a date such as 2027-01-31, which ends at the close of that day in UTC. Add --dry-run to see who would gain what first.

A path names a repository if there is one at it, and a group otherwise. Add --output json to any of the three for the full answer instead of the summary.

Know when access ends

Access with an end date stops on its own: the next request after the date is refused, with nothing to remember to undo. A week before the end, the person holding it and whoever gave it each get an item in their attention inbox, once. A month after the end, the lapsed grant is removed from the list; until then an explanation shows it as expired.

Advanced: cap what someone can do, whatever they are given

A limit sets the most a person, a team, every service account, every AI agent, or everyone can do on a group or repository and everything beneath it — Contractors at most Reporter on billing, service accounts at most Developer anywhere, everyone read-only on the archive. Grants still say what people can do; a limit takes away whatever goes above it. A limit reaches everything beneath where it is set, even a repository that has stopped inheriting access, so switching that off can never undo it. The organisation's Owners are never limited.

A limit that allows nothing on a Public or Internal group or repository removes every grant, but the person can still read what the visibility lets anyone read — the answer says so with a warning.

Only an Owner sets and removes limits, and a token needs access:administer, which no bundle includes. Add dry_run=true to see who a limit would narrow before setting it.

On the list of who has access, a grant that a limit narrows carries that limit in limited_to — whether the limit names the person, a team they are on, or everyone — so the cap shows on the row it caps.

Advanced: only people added here

Switch off inheritance on a group or repository, and grants made on the groups above stop reaching it: only the people given access there, or beneath it, keep theirs. The incident repository for the security team is the classic case — everyone is Developer at the top, and still nobody but the security team can open it. Limits still reach it, and the organisation's Owners are never shut out.

Only an Owner switches this, with access:administer. A top-level group has nothing above it, so it cannot be switched. Switching it off is refused when it would take away your own right to switch it back; ask an Owner of the organisation. Add dry_run=true to see who would lose access first.

See everyone in your organisation

Everyone who holds access anywhere in your organisation — people and service accounts — longest-standing first: whether they are a member — access at the top-level group, or a place on one of its teams — or an outside collaborator, whose access is all further down; how many grants name them directly; their teams; their role at the top, when a grant there names them; when they were first given access; and when they last used any of it. Filter by kind with kind=member or kind=outside_collaborator, or search by username. Access that has ended does not count.

Ask it of your organisation's top-level group; a subgroup is refused with NOT_AN_ORGANIZATION.

Review your organisation's access

The review is the list an Owner works through every quarter: every grant with a reason to look at it, oldest first, each with its reasons.

A grant is used when it lets someone do something — read a page, push a commit, approve a merge. Gitmoap notes the day, once a day, so last_exercised_at on a grant says when that last happened. Access reached only through a public or internal group's visibility is not a use of any grant.

A grant can have several reasons, and access that has already ended is not listed. Only the organisation's Owners can read the review: it lists access on groups and repositories that others may not be able to see. Ask for one reason at a time with reason. A page can hold fewer grants than you asked for — even none — while more remain, because each request reads a bounded stretch of the organisation's grants: keep reading while next_token comes back.

Revoke several grants at once

Name up to 100 of your organisation's grants, by id, on its top-level group — you need Reporter there; naming one twice counts once. Each is checked as if you were revoking it for someone else on its own — you need Maintainer where it was made, and to hold its role yourself — and they all go together or none do: if one would leave the organisation without an Owner, is a service account's own level, or is one you could not revoke, nothing is revoked. A grant you cannot see, or one from another organisation, is refused as not found, for the whole request. To give up your own access, revoke that grant on its own.

Look up what a role can do

Every permission a role can hold, how sensitive it is, whether visibility alone allows it, and the lowest built-in role that has it; plus the five built-in roles, each with everything it holds. Anyone can read it, signed in or not.

Reference

Limits

Grants per group or repository — 50 on the Free plan. People, service accounts and teams given access on one group or repository all count, each once, whatever role they hold. A service account's own level on its home does not count here; it counts against the service-account limit instead.

At the limit, giving more access is refused with 429 TOO_MANY_REQUESTS and nothing is written. Revoke grants that are no longer needed, give a team access instead of each of its members, or raise the limit: a higher plan lifts every group's and repository's allowance, and an Owner can ask for a higher limit on one namespace.

One request names at most 50 subjects, and an end date can be at most a year away.

A bulk revocation names at most 100 grants. Split a longer list into several requests; each is all or nothing on its own.

The access review reads at most 1 000 grants per request. In a large organisation a page can come back short, or empty, with a next_token; keep reading until none comes back.

Limits per group or repository — 10 on the Free plan; 50 on Pro, 100 on Team, 200 on Enterprise. One subject is limited at most once on one group or repository.

Troubleshooting

Examples

Give eight people one product

Everyone on a small team gets Developer on the organisation, in one request, and every repository in it — private ones included — is theirs to push to.

Give a contractor access that ends on its own

Check whether someone can push, and why

Review everyone given access directly to a repository

Clear out access nobody uses

FAQ

Related