| 1 | --- |
| 2 | title: Access and roles |
| 3 | description: The five repository roles and what each can do, the base permission members get, the Admin role a repository's creator gets, security managers, roles through teams, outside collaborators and invitations, who may manage deploy keys, and what agents may do on a person's behalf. |
| 4 | --- |
| 5 | |
| 6 | Everyone who can work in a repository has a role on it. The role says what |
| 7 | they can do there, from reading it to managing who else has access. A |
| 8 | workspace gives its members a role on every one of its repositories, a |
| 9 | repository can give anyone a role of their own: a member who needs more |
| 10 | there, or someone outside the workspace, and it can give a |
| 11 | [team](/guides/teams/) a role that everyone in the team has. |
| 12 | |
| 13 | ## The roles |
| 14 | |
| 15 | | Role | For | |
| 16 | | --- | --- | |
| 17 | | **Read** | Read and clone; open issues and pull requests, and comment. | |
| 18 | | **Triage** | Read, and manage issues and pull requests: apply labels and milestones, assign, close. | |
| 19 | | **Write** | Triage, and push, merge, manage labels and milestones, see security alerts, and put agents to work. | |
| 20 | | **Maintain** | Write, and manage the repository's settings and topics. | |
| 21 | | **Admin** | Everything: branch protection and rulesets, webhooks, secrets, deployments, security settings, who has access, and the repository's name, visibility and archiving. | |
| 22 | |
| 23 | Each role has everything the one above it has. |
| 24 | |
| 25 | ## What each role can do |
| 26 | |
| 27 | | | Read | Triage | Write | Maintain | Admin | |
| 28 | | --- | --- | --- | --- | --- | --- | |
| 29 | | See code, issues and pull requests; clone and fetch | Yes | Yes | Yes | Yes | Yes | |
| 30 | | Open issues and pull requests, and comment | Yes | Yes | Yes | Yes | Yes | |
| 31 | | Apply labels and milestones; assign, close and reopen issues and pull requests | | Yes | Yes | Yes | Yes | |
| 32 | | Push to branches that are not protected | | | Yes | Yes | Yes | |
| 33 | | Merge pull requests and use the merge queue | | | Yes | Yes | Yes | |
| 34 | | Create, edit and delete labels and milestones | | | Yes | Yes | Yes | |
| 35 | | See and dismiss security alerts | | | Yes | Yes | Yes | |
| 36 | | Assign agents and start runs, plans and workflows | | | Yes | Yes | Yes | |
| 37 | | Change the description, topics, and pull request and agent settings | | | | Yes | Yes | |
| 38 | | Change branch protection, rulesets and guardrails | | | | | Yes | |
| 39 | | Change security settings, custom patterns and bypass reviews | | | | | Yes | |
| 40 | | Manage webhooks, secrets, variables, deployments and domains | | | | | Yes | |
| 41 | | Manage who has access, invitations and deploy keys | | | | | Yes | |
| 42 | | Rename, archive and change the default branch | | | | | Yes | |
| 43 | | Change visibility | | | | | Yes, if the [member privileges](/guides/workspaces/#member-privileges) allow | |
| 44 | | Transfer or delete the repository | | | | | Owners, or Admins if the member privileges allow | |
| 45 | |
| 46 | Everyone can edit and delete their own comments. Maintain and Admin can |
| 47 | edit and delete anyone's; see |
| 48 | [editing and deleting comments](/guides/pull-requests/#editing-and-deleting-comments). |
| 49 | |
| 50 | Changing a repository's visibility, transferring it and deleting it also |
| 51 | depend on its workspace's [member privileges](/guides/workspaces/#member-privileges). |
| 52 | By default, a member with Admin can change visibility, and only an owner |
| 53 | can transfer or delete. Someone given Admin on one repository without being |
| 54 | a member, an outside collaborator, can do none of the three. |
| 55 | |
| 56 | Some things work a little differently on g1t: |
| 57 | |
| 58 | - Whoever opened an issue or pull request can still edit, label and close |
| 59 | their own, whatever their role. |
| 60 | - A [protected branch](/guides/git/#protected-branches) takes no pushes |
| 61 | from anyone, Maintain and Admin included. To let a role push, list it as |
| 62 | a bypass actor of a [ruleset](/guides/rules/) instead. |
| 63 | - Applying a label the repository does not have yet creates it, for |
| 64 | someone with Write. |
| 65 | |
| 66 | Read and Triage cannot put agents to work, or start anything else that |
| 67 | spends compute: runs, plans, workflows and deployments need Write. |
| 68 | |
| 69 | ## How your role is worked out |
| 70 | |
| 71 | Your role on a repository is the highest of: |
| 72 | |
| 73 | 1. **Ownership.** An owner of the workspace has Admin on every repository |
| 74 | in it. |
| 75 | 2. **The base permission.** Every member of the workspace gets the |
| 76 | workspace's [base permission](#the-base-permission) on every repository |
| 77 | in it. |
| 78 | 3. **A role given to you on that repository.** See |
| 79 | [add someone to a repository](#add-someone-to-a-repository). Whoever |
| 80 | creates a repository is given Admin on it this way, so it stays theirs |
| 81 | to run whatever the base permission is. |
| 82 | 4. **Security manager.** A member who is one of the workspace's |
| 83 | [security managers](/guides/workspaces/#roles-that-add-to-a-member) |
| 84 | has Read on every repository, and can see and manage its security |
| 85 | alerts and security settings whatever their role. |
| 86 | 5. **Your teams.** The role each [team](/guides/teams/) you are in has on |
| 87 | that repository, and the roles of that team's parent teams, which child |
| 88 | teams inherit. See [repository access](/guides/teams/#repository-access). |
| 89 | 6. **Public.** Anyone, signed in or not, can read a public repository. |
| 90 | |
| 91 | The highest wins. A member whose base permission is Read and who is given |
| 92 | Maintain on one repository has Maintain there and Read everywhere else. A |
| 93 | role lower than what you already have changes nothing. When a role given to |
| 94 | you and a team's role are the same, the one given to you is shown as where |
| 95 | it comes from. |
| 96 | |
| 97 | A workspace's own [access token](/guides/workspaces/#workspace-access-tokens) |
| 98 | has Write on its workspace's repositories, as a member does, and none on any |
| 99 | other. An owner can give one Admin instead, only when making it. A workflow |
| 100 | job's token and a [deploy key](/guides/git/#deploy-keys) have Write at most, |
| 101 | on their one repository. What is for people only, such as transferring or |
| 102 | deleting a repository, still needs a person. |
| 103 | |
| 104 | A [fine-grained personal access token](/guides/authentication/#create-a-fine-grained-token) |
| 105 | has your role only in its resource owner's repositories that it reaches: |
| 106 | all of them, the ones chosen, or none. Everywhere else it reads public |
| 107 | repositories, as anyone can, and does nothing more. A classic token has |
| 108 | your role wherever you have one, unless a workspace's |
| 109 | [rules for tokens](/guides/authentication/#a-workspaces-rules-for-tokens) |
| 110 | keep it out. |
| 111 | |
| 112 | ### Private repositories |
| 113 | |
| 114 | Someone without at least Read on a private repository cannot tell it |
| 115 | exists: its pages answer 404, and the API answers `404` with |
| 116 | `Repository not found.`, the same as for a repository that does not exist. |
| 117 | Someone who can read it but lacks the role for what they tried gets `403` |
| 118 | and a message naming the role they need: |
| 119 | |
| 120 | ```text |
| 121 | You need the Admin role or higher on acme/rocket to do that. |
| 122 | ``` |
| 123 | |
| 124 | ### Git |
| 125 | |
| 126 | | | Needs | |
| 127 | | --- | --- | |
| 128 | | `git clone`, `fetch`, `pull` | Read | |
| 129 | | `git push` | Write | |
| 130 | |
| 131 | A [protected branch](/guides/git/#protected-branches) refuses pushes from |
| 132 | everyone, whatever their role, Admin included; changes reach it through |
| 133 | pull requests. |
| 134 | |
| 135 | ## The base permission |
| 136 | |
| 137 | The base permission is what every member of a workspace gets on every one |
| 138 | of its repositories: |
| 139 | |
| 140 | | Base permission | Members get | |
| 141 | | --- | --- | |
| 142 | | **None** | Nothing beyond what is public. Members see only the private repositories they are given a role on. | |
| 143 | | **Read** | Read on every repository. What a new workspace starts with. | |
| 144 | | **Write** | Write on every repository. | |
| 145 | | **Admin** | Admin on every repository. Transferring and deleting stay with owners unless the member privileges allow them. | |
| 146 | |
| 147 | Owners always have Admin, whatever it says. Only owners can change it: |
| 148 | |
| 149 | 1. Open the workspace's **People** in the sidebar, `g1t.sh/<workspace>/-/people`. Every member can see it; owners manage it. |
| 150 | 2. Under **Base permission**, choose one. |
| 151 | |
| 152 | It takes effect on everyone's next request. To give one member more on |
| 153 | one repository, give them a role there; to give them less, lower the base |
| 154 | permission and give roles to the people who need them. Whoever creates a |
| 155 | repository keeps Admin on it however low the base permission is. |
| 156 | |
| 157 | ### What changed for existing members |
| 158 | |
| 159 | A workspace made from 2026-10-08 starts at **Read**. One made before keeps |
| 160 | the base permission it had, **Write** unless an owner changed it. |
| 161 | |
| 162 | Before roles, every member of a workspace could also change a repository's |
| 163 | settings, its branch protection and guardrails, webhooks, secrets and |
| 164 | variables, deployments and domains. With Write, members keep pushing, |
| 165 | merging and putting agents to work; changing settings now needs Maintain, |
| 166 | and branch protection, rulesets, guardrails and the rest Admin. Owners |
| 167 | have Admin, so they keep all of it. |
| 168 | |
| 169 | On 2026-10-08 the roles were brought in line with the table above: |
| 170 | |
| 171 | - Branch protection, rulesets and guardrails moved from Maintain to Admin. |
| 172 | - Creating, editing and deleting labels and milestones moved from Triage |
| 173 | to Write; Triage still applies them. |
| 174 | - Seeing and dismissing security alerts, secrets included, takes Write; |
| 175 | changing security settings and custom patterns takes Admin. |
| 176 | - Whoever made each existing repository and is still a member of its |
| 177 | workspace was given Admin on it, unless they had it already. |
| 178 | |
| 179 | To give members everything they had before, an owner sets the base |
| 180 | permission to **Admin**. They then also get what only owners could do |
| 181 | before: managing who has access, renaming and archiving repositories, and |
| 182 | changing their visibility and default branch. |
| 183 | |
| 184 | ## Add someone to a repository |
| 185 | |
| 186 | You need Admin on the repository and a confirmed email address. |
| 187 | |
| 188 | 1. Open the repository's **Settings → Access**, |
| 189 | `g1t.sh/<workspace>/<repo>/settings/access`. |
| 190 | 2. Under **Add people**, type a username or an email address. |
| 191 | 3. Pick their role and choose **Add**. |
| 192 | |
| 193 | Everyone with access is listed under **People with access**, with their |
| 194 | role and where it comes from: owner, the base permission, a role given to |
| 195 | them, or **Through team** and the team's slug. **Teams with access** lists the |
| 196 | teams given a role on it, with how many people each has. People with Write |
| 197 | or Maintain can see the lists; changing them needs Admin. |
| 198 | |
| 199 | Giving a role to someone outside the workspace takes an owner when the |
| 200 | workspace's [member privileges](/guides/workspaces/#member-privileges) turn |
| 201 | off **Repository admins can add outside collaborators**. |
| 202 | |
| 203 | Someone with Admin can give a team a role under **Teams with access**: |
| 204 | pick the team and its role, and add it. Only the workspace's own teams can |
| 205 | be added. See [teams](/guides/teams/#repository-access). |
| 206 | |
| 207 | What happens depends on who they are: |
| 208 | |
| 209 | | Who | What happens | |
| 210 | | --- | --- | |
| 211 | | A member of the workspace | They have the role at once. It matters only where it is higher than the base permission. | |
| 212 | | Someone else on g1t | They are sent an [invitation](#invitations) to accept. Typing the confirmed email address of someone on g1t does the same. | |
| 213 | | An email address with no g1t account | g1t emails an invite code that only that address can use. Signing up with it makes their account and accepts the invitation in one step. | |
| 214 | |
| 215 | An invite code to someone without an account uses one of the workspace's |
| 216 | granted invites, or else one of yours (see |
| 217 | [invites](/guides/authentication/#invites)), and works for 30 days. |
| 218 | |
| 219 | On a free workspace, only the first row works: its members can be given a |
| 220 | role, but nobody else can be invited until the workspace starts the g1t |
| 221 | plan. **Add people** says **Start the plan to invite people** above the |
| 222 | form, and an invitation is refused with `402` (`payment_required`). An |
| 223 | invitation sent before cannot be accepted until then. See |
| 224 | [who a free workspace can add](/guides/usage-and-billing/#who-a-free-workspace-can-add). |
| 225 | |
| 226 | To change someone's role, pick another beside their name. To take it away, |
| 227 | choose **Remove**. Removing takes away only the role given on this |
| 228 | repository: an owner's Admin, a member's base permission and what their |
| 229 | teams give them stay. Anyone |
| 230 | can remove their own role from a repository. Each change is confirmed |
| 231 | under the list; one that is refused says why on that person's row. |
| 232 | |
| 233 | ## Outside collaborators |
| 234 | |
| 235 | An outside collaborator has a role on some of a workspace's repositories |
| 236 | without being a member of it. They: |
| 237 | |
| 238 | - see the repositories shared with them under **Shared with you** in the |
| 239 | sidebar, and only those: not the workspace's other private |
| 240 | repositories, its members, settings, usage or billing. The workspace's |
| 241 | page, `g1t.sh/<workspace>`, shows them its public repositories and the |
| 242 | ones shared with them; |
| 243 | - can do on each repository what their role allows, and nothing in the |
| 244 | workspace itself, such as its webhooks, secrets, tokens or integrations; |
| 245 | - are held to whatever the workspace asks of its members, checked when |
| 246 | they are added, when they accept, and on every request after. |
| 247 | |
| 248 | - can put agents to work where they have Write; the runs are charged to |
| 249 | the repository's workspace, and they do not see which model ran or what |
| 250 | it cost. An agent working for them is told the project's memory, never |
| 251 | the workspace's. |
| 252 | |
| 253 | Owners see every outside collaborator, and the repositories and roles each |
| 254 | has, on the **Outside collaborators** tab of the workspace's |
| 255 | **People**. **Convert to member** adds one to the workspace |
| 256 | (see [members and roles](/guides/workspaces/#members-and-roles)); the |
| 257 | roles they have stay, and the base permission adds to them. |
| 258 | |
| 259 | Removing a member from a workspace, or their leaving it, also removes the |
| 260 | roles they were given on its repositories, and takes them out of its teams. |
| 261 | |
| 262 | A workspace that [requires two-factor authentication](/guides/authentication/#require-two-factor-authentication) |
| 263 | holds its outside collaborators to it as it does its members: without it, |
| 264 | they cannot reach its repositories until they turn it on. |
| 265 | |
| 266 | ## Invitations |
| 267 | |
| 268 | An invitation to someone on g1t waits for them to answer, and they are |
| 269 | emailed a link to it. |
| 270 | |
| 271 | 1. Open `g1t.sh/<workspace>/<repo>/invitations`, the link in the email. |
| 272 | 2. Choose **Accept invitation** or **Decline**. |
| 273 | |
| 274 | Accepting gives you the role; you then find the repository under **Shared |
| 275 | with you**. An invitation lasts **7 days**, then expires. Until it is |
| 276 | answered, it is listed as pending on the repository's **Settings → Access**, |
| 277 | where someone with Admin can change its role or **Revoke** it. To invite |
| 278 | someone again after an expired or declined invitation, add them again. |
| 279 | |
| 280 | ## Agents |
| 281 | |
| 282 | An agent works with the role of the person it acts for, on the |
| 283 | repository it works in, and never more than Write. An owner's agent has |
| 284 | Write, not Admin. So an agent working for you can push, open and merge |
| 285 | pull requests where you can, and cannot change settings, protection, |
| 286 | webhooks or secrets, even when you can. |
| 287 | |
| 288 | An agent's credential can never change who has access: it cannot add, |
| 289 | remove or invite anyone, answer an invitation, or change the base |
| 290 | permission. When the person it works for loses their role on the |
| 291 | repository, or leaves the workspace, the agent loses it too. See |
| 292 | [credentials](/guides/working-with-g1t/#credentials). |
| 293 | |
| 294 | Because putting agents to work spends compute, it needs Write. Someone with |
| 295 | Read or Triage who mentions or assigns an agent is told so, and nothing |
| 296 | starts. |
| 297 | |
| 298 | ## Deploy keys |
| 299 | |
| 300 | A [deploy key](/guides/git/#deploy-keys) is an SSH key that lets a machine |
| 301 | reach one repository: Read, or Write when it was added with write access, |
| 302 | on that repository and no other. It is part of who has access, so managing |
| 303 | deploy keys needs the Admin role: |
| 304 | |
| 305 | | Who | Can list, add and delete a repository's deploy keys | |
| 306 | | --- | --- | |
| 307 | | Someone with the Admin role on it, owners included | Yes | |
| 308 | | Someone with Maintain or less | No | |
| 309 | | An agent, whoever it works for | No | |
| 310 | | A workspace's [access token](/guides/workspaces/#workspace-access-tokens) | Only when an owner gave it Admin | |
| 311 | | A deploy key | No | |
| 312 | |
| 313 | Adding one also needs a confirmed email address. A personal access token |
| 314 | needs the `access:read` scope to list and read them, and `access:admin` to |
| 315 | add and delete them. |
| 316 | |
| 317 | ## Through the API |
| 318 | |
| 319 | Every route is in the [API reference](/reference/api/). Each is also an |
| 320 | action of an [MCP tool](/reference/mcp/): `access` for a repository's |
| 321 | people, its deploy keys and the base permission, `account` for invitations to you. |
| 322 | |
| 323 | | Route | MCP tool and action | What it does | Who | |
| 324 | | --- | --- | --- | --- | |
| 325 | | `GET /repos/{owner}/{name}/collaborators` | `access` `list_collaborators` | Everyone with access to a repository, their role and where it comes from. | Write | |
| 326 | | `GET /repos/{owner}/{name}/collaborators/{username}/permission` | `access` `get_permission` | One person's role on a repository and what it lets them do. | Write, or about yourself | |
| 327 | | `POST /repos/{owner}/{name}/collaborators` | `access` `add_collaborator` | Give someone a role. Body: `invitee` (a username or an email address) and `role`. Answers with `result`: `granted` or `invited`. | Admin | |
| 328 | | `PATCH /repos/{owner}/{name}/collaborators/{username}` | `access` `update_collaborator` | Change someone's role, or a pending invitation's. Body: `role`. | Admin | |
| 329 | | `DELETE /repos/{owner}/{name}/collaborators/{username}` | `access` `remove_collaborator` | Take away the role given to someone on the repository. | Admin, or yourself | |
| 330 | | `GET /repos/{owner}/{name}/invitations` | `access` `list_invitations` | A repository's pending invitations. | Admin | |
| 331 | | `DELETE /repos/{owner}/{name}/invitations/{id}` | `access` `revoke_invitation` | Withdraw a pending invitation. | Admin | |
| 332 | | `GET /user/repository_invitations` | `account` `list_repository_invitations` | The invitations waiting for you. | You | |
| 333 | | `PATCH /user/repository_invitations/{id}` | `account` `accept_repository_invitation` | Accept one. | You | |
| 334 | | `DELETE /user/repository_invitations/{id}` | `account` `decline_repository_invitation` | Decline one. | You | |
| 335 | | `PUT /workspaces/{workspace}/base_permission` | `access` `set_base_permission` | Set the base permission. Body: `base_permission`: `none`, `read`, `write` or `admin`. `PATCH /workspaces/{workspace}` (`workspace` `update`) takes `base_permission` too, with the `access:admin` scope. | Owners | |
| 336 | | `GET /workspaces/{workspace}/outside_collaborators` | `access` `list_outside_collaborators` | A workspace's outside collaborators and the repositories each can reach. | Owners | |
| 337 | | `GET /repos/{owner}/{name}/keys` | `access` `list_deploy_keys` | A repository's [deploy keys](/guides/git/#deploy-keys). | Admin | |
| 338 | | `GET /repos/{owner}/{name}/keys/{id}` | `access` `get_deploy_key` | One deploy key. | Admin | |
| 339 | | `POST /repos/{owner}/{name}/keys` | `access` `add_deploy_key` | Add a deploy key. Body: `title`, `key` and `read_only` (true unless you send false). | Admin | |
| 340 | | `DELETE /repos/{owner}/{name}/keys/{id}` | `access` `remove_deploy_key` | Delete a deploy key. | Admin | |
| 341 | |
| 342 | Changing who has access, answering an invitation and setting the base |
| 343 | permission are for people, signed in or with a personal access token. |
| 344 | |
| 345 | Roles are written `read`, `triage`, `write`, `maintain` and `admin`. |
| 346 | |
| 347 | ```sh |
| 348 | curl https://api.g1t.sh/repos/acme/rocket/collaborators/ada/permission \ |
| 349 | -H "Authorization: Bearer $G1T_TOKEN" |
| 350 | ``` |
| 351 | |
| 352 | ```json |
| 353 | { |
| 354 | "username": "ada", |
| 355 | "role": "write", |
| 356 | "source": "base", |
| 357 | "capabilities": ["read", "participate", "triage", "push", "merge", "manage_labels", "security_alerts", "run"] |
| 358 | } |
| 359 | ``` |
| 360 | |
| 361 | `source` is `owner`, `base`, `direct` or `team`. In the list from |
| 362 | `list_collaborators`, each person also has `direct`, the role given to them |
| 363 | on the repository if any, and `team_role` and `team`: the highest role a |
| 364 | team gives them there, and that team's slug. A team's own roles are managed |
| 365 | through the [teams API](/guides/teams/#through-the-api). |
| 366 | |
| 367 | ## Webhooks and the audit log |
| 368 | |
| 369 | A change to someone's role on a repository is sent to |
| 370 | [webhooks](/guides/webhooks/) as one of: |
| 371 | |
| 372 | | Event | When | |
| 373 | | --- | --- | |
| 374 | | `repo.collaborator_added` | Someone was given a role on the repository, or accepted an invitation. | |
| 375 | | `repo.collaborator_role_changed` | Their role changed. `data.role` and `data.previous_role`. | |
| 376 | | `repo.collaborator_removed` | Their role was taken away. | |
| 377 | |
| 378 | Each has `data.username`, `data.role` and `data.previous_role`. |
| 379 | |
| 380 | The workspace's [audit log](/guides/audit-log/) records the same changes |
| 381 | under those names, and also `repo.invitation_created`, |
| 382 | `repo.invitation_revoked`, `workspace.base_permission_changed`, and |
| 383 | `repo.deploy_key_added` and `repo.deploy_key_removed` for |
| 384 | [deploy keys](#deploy-keys). A repository's creator being given Admin is |
| 385 | not recorded: it comes with `repo.created`. |
| 386 | |
| 387 | A team's role on a repository changing is sent as `team.repo_added`, |
| 388 | `team.repo_role_changed` or `team.repo_removed`; see |
| 389 | [teams](/guides/teams/#webhooks-and-the-audit-log). |