| 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 [personal access token](/guides/authentication/#where-a-token-reaches) |
| 105 | made for one workspace has your role only in that workspace's repositories |
| 106 | that it reaches: all of them, the ones chosen, or none. Everywhere else it |
| 107 | reads public repositories, as anyone can, and does nothing more. A token |
| 108 | made for all your workspaces has your role wherever you have one, unless a |
| 109 | workspace's |
| 110 | [rules for tokens](/guides/authentication/#a-workspaces-rules-for-tokens) |
| 111 | keep it out. |
| 112 | |
| 113 | ### Private repositories |
| 114 | |
| 115 | Someone without at least Read on a private repository cannot tell it |
| 116 | exists: its pages answer 404, and the API answers `404` with |
| 117 | `Repository not found.`, the same as for a repository that does not exist. |
| 118 | Someone who can read it but lacks the role for what they tried gets `403` |
| 119 | and a message naming the role they need: |
| 120 | |
| 121 | ```text |
| 122 | You need the Admin role or higher on acme/rocket to do that. |
| 123 | ``` |
| 124 | |
| 125 | ### Git |
| 126 | |
| 127 | | | Needs | |
| 128 | | --- | --- | |
| 129 | | `git clone`, `fetch`, `pull` | Read | |
| 130 | | `git push` | Write | |
| 131 | |
| 132 | A [protected branch](/guides/git/#protected-branches) refuses pushes from |
| 133 | everyone, whatever their role, Admin included; changes reach it through |
| 134 | pull requests. |
| 135 | |
| 136 | ## The base permission |
| 137 | |
| 138 | The base permission is what every member of a workspace gets on every one |
| 139 | of its repositories: |
| 140 | |
| 141 | | Base permission | Members get | |
| 142 | | --- | --- | |
| 143 | | **None** | Nothing beyond what is public. Members see only the private repositories they are given a role on. | |
| 144 | | **Read** | Read on every repository. What a new workspace starts with. | |
| 145 | | **Write** | Write on every repository. | |
| 146 | | **Admin** | Admin on every repository. Transferring and deleting stay with owners unless the member privileges allow them. | |
| 147 | |
| 148 | Owners always have Admin, whatever it says. Only owners can change it: |
| 149 | |
| 150 | 1. Open **Workspace → Access → Permissions**, `g1t.sh/<workspace>/-/permissions`. Owners only. |
| 151 | 2. In the **Code** card, under **Base permission**, choose one and select **Save**. |
| 152 | |
| 153 | Every other who-may-do-what setting is on the same page: see |
| 154 | [permissions](/guides/permissions/). |
| 155 | |
| 156 | It takes effect on everyone's next request. To give one member more on |
| 157 | one repository, give them a role there; to give them less, lower the base |
| 158 | permission and give roles to the people who need them. Whoever creates a |
| 159 | repository keeps Admin on it however low the base permission is. |
| 160 | |
| 161 | ### What changed for existing members |
| 162 | |
| 163 | A workspace made from 2026-10-08 starts at **Read**. One made before keeps |
| 164 | the base permission it had, **Write** unless an owner changed it. |
| 165 | |
| 166 | Before roles, every member of a workspace could also change a repository's |
| 167 | settings, its branch protection and guardrails, webhooks, secrets and |
| 168 | variables, deployments and domains. With Write, members keep pushing, |
| 169 | merging and putting agents to work; changing settings now needs Maintain, |
| 170 | and branch protection, rulesets, guardrails and the rest Admin. Owners |
| 171 | have Admin, so they keep all of it. |
| 172 | |
| 173 | On 2026-10-08 the roles were brought in line with the table above: |
| 174 | |
| 175 | - Branch protection, rulesets and guardrails moved from Maintain to Admin. |
| 176 | - Creating, editing and deleting labels and milestones moved from Triage |
| 177 | to Write; Triage still applies them. |
| 178 | - Seeing and dismissing security alerts, secrets included, takes Write; |
| 179 | changing security settings and custom patterns takes Admin. |
| 180 | - Whoever made each existing repository and is still a member of its |
| 181 | workspace was given Admin on it, unless they had it already. |
| 182 | |
| 183 | To give members everything they had before, an owner sets the base |
| 184 | permission to **Admin**. They then also get what only owners could do |
| 185 | before: managing who has access, renaming and archiving repositories, and |
| 186 | changing their visibility and default branch. |
| 187 | |
| 188 | ## Add someone to a repository |
| 189 | |
| 190 | You need Admin on the repository and a confirmed email address. |
| 191 | |
| 192 | 1. Open the repository's **Settings → Access**, |
| 193 | `g1t.sh/<workspace>/<repo>/settings/access`. |
| 194 | 2. Under **Add people**, type a username or an email address. |
| 195 | 3. Pick their role and choose **Add**. |
| 196 | |
| 197 | Everyone with access is listed under **People with access**, with their |
| 198 | role and where it comes from: owner, the base permission, a role given to |
| 199 | them, or **Through team** and the team's slug. **Teams with access** lists the |
| 200 | teams given a role on it, with how many people each has. People with Write |
| 201 | or Maintain can see the lists; changing them needs Admin. |
| 202 | |
| 203 | Giving a role to someone outside the workspace takes an owner when the |
| 204 | workspace's [member privileges](/guides/workspaces/#member-privileges) turn |
| 205 | off **Repository admins can add outside collaborators**. |
| 206 | |
| 207 | Someone with Admin can give a team a role under **Teams with access**: |
| 208 | pick the team and its role, and add it. Only the workspace's own teams can |
| 209 | be added. See [teams](/guides/teams/#repository-access). |
| 210 | |
| 211 | What happens depends on who they are: |
| 212 | |
| 213 | | Who | What happens | |
| 214 | | --- | --- | |
| 215 | | A member of the workspace | They have the role at once. It matters only where it is higher than the base permission. | |
| 216 | | Someone else on g1t | They are sent an [invitation](#invitations) to accept. Typing the confirmed email address of someone on g1t does the same. | |
| 217 | | 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. | |
| 218 | |
| 219 | An invite code to someone without an account uses one of the workspace's |
| 220 | granted invites, or else one of yours (see |
| 221 | [invites](/guides/authentication/#invites)), and works for 30 days. |
| 222 | |
| 223 | On a free workspace, only the first row works: its members can be given a |
| 224 | role, but nobody else can be invited until the workspace starts the g1t |
| 225 | plan. **Add people** says **Start the plan to invite people** above the |
| 226 | form, and an invitation is refused with `402` (`payment_required`). An |
| 227 | invitation sent before cannot be accepted until then. See |
| 228 | [who a free workspace can add](/guides/usage-and-billing/#who-a-free-workspace-can-add). |
| 229 | |
| 230 | To change someone's role, pick another beside their name. To take it away, |
| 231 | choose **Remove**. Removing takes away only the role given on this |
| 232 | repository: an owner's Admin, a member's base permission and what their |
| 233 | teams give them stay. Anyone |
| 234 | can remove their own role from a repository. Each change is confirmed |
| 235 | under the list; one that is refused says why on that person's row. |
| 236 | |
| 237 | ## Outside collaborators |
| 238 | |
| 239 | An outside collaborator has a role on some of a workspace's repositories |
| 240 | without being a member of it. They: |
| 241 | |
| 242 | - see the repositories shared with them under **Shared with you** in the |
| 243 | sidebar, and only those: not the workspace's other private |
| 244 | repositories, its members, settings, usage or billing. The workspace's |
| 245 | page, `g1t.sh/<workspace>`, shows them its public repositories and the |
| 246 | ones shared with them; |
| 247 | - can do on each repository what their role allows, and nothing in the |
| 248 | workspace itself, such as its webhooks, secrets, tokens or integrations; |
| 249 | - are held to whatever the workspace asks of its members, checked when |
| 250 | they are added, when they accept, and on every request after. |
| 251 | |
| 252 | - can put agents to work where they have Write; the runs are charged to |
| 253 | the repository's workspace, and they do not see which model ran or what |
| 254 | it cost. An agent working for them is told the project's memory, never |
| 255 | the workspace's. |
| 256 | |
| 257 | Owners see every outside collaborator, and the repositories and roles each |
| 258 | has, on the **Outside collaborators** tab of the workspace's |
| 259 | **Members** page, `g1t.sh/<workspace>/-/members`. **Invite as a member** sends one an invitation to join the |
| 260 | workspace as a member (see [add people](/guides/workspaces/#add-people)); |
| 261 | once they accept, the roles they have stay, and the base permission adds |
| 262 | to them. |
| 263 | |
| 264 | Removing a member from a workspace, or their leaving it, also removes the |
| 265 | roles they were given on its repositories, and takes them out of its teams. |
| 266 | |
| 267 | A workspace that [requires two-factor authentication](/guides/authentication/#require-two-factor-authentication) |
| 268 | holds its outside collaborators to it as it does its members: without it, |
| 269 | they cannot reach its repositories until they turn it on. |
| 270 | |
| 271 | ## Invitations |
| 272 | |
| 273 | An invitation to someone on g1t waits for them to answer, and they are |
| 274 | emailed a link to it. |
| 275 | |
| 276 | 1. Open `g1t.sh/<workspace>/<repo>/invitations`, the link in the email. |
| 277 | 2. Choose **Accept invitation** or **Decline**. |
| 278 | |
| 279 | Accepting gives you the role; you then find the repository under **Shared |
| 280 | with you**. An invitation lasts **7 days**, then expires. Until it is |
| 281 | answered, it is listed as pending on the repository's **Settings → Access**, |
| 282 | where someone with Admin can change its role or **Revoke** it. To invite |
| 283 | someone again after an expired or declined invitation, add them again. |
| 284 | |
| 285 | ## Agents |
| 286 | |
| 287 | An agent works with the role of the person it acts for, on the |
| 288 | repository it works in, and never more than Write. An owner's agent has |
| 289 | Write, not Admin. So an agent working for you can push, open and merge |
| 290 | pull requests where you can, and cannot change settings, protection, |
| 291 | webhooks or secrets, even when you can. |
| 292 | |
| 293 | An agent's credential can never change who has access: it cannot add, |
| 294 | remove or invite anyone, answer an invitation, or change the base |
| 295 | permission. When the person it works for loses their role on the |
| 296 | repository, or leaves the workspace, the agent loses it too. See |
| 297 | [credentials](/guides/working-with-g1t/#credentials). |
| 298 | |
| 299 | Because putting agents to work spends compute, it needs Write. Someone with |
| 300 | Read or Triage who mentions or assigns an agent is told so, and nothing |
| 301 | starts. |
| 302 | |
| 303 | ## Deploy keys |
| 304 | |
| 305 | A [deploy key](/guides/git/#deploy-keys) is an SSH key that lets a machine |
| 306 | reach one repository: Read, or Write when it was added with write access, |
| 307 | on that repository and no other. It is part of who has access, so managing |
| 308 | deploy keys needs the Admin role: |
| 309 | |
| 310 | | Who | Can list, add and delete a repository's deploy keys | |
| 311 | | --- | --- | |
| 312 | | Someone with the Admin role on it, owners included | Yes | |
| 313 | | Someone with Maintain or less | No | |
| 314 | | An agent, whoever it works for | No | |
| 315 | | A workspace's [access token](/guides/workspaces/#workspace-access-tokens) | Only when an owner gave it Admin | |
| 316 | | A deploy key | No | |
| 317 | |
| 318 | Adding one also needs a confirmed email address. A personal access token |
| 319 | needs the `access:read` scope to list and read them, and `access:admin` to |
| 320 | add and delete them. |
| 321 | |
| 322 | ## Through the API |
| 323 | |
| 324 | Every route is in the [API reference](/reference/api/). Each is also an |
| 325 | action of an [MCP tool](/reference/mcp/): `access` for a repository's |
| 326 | people, its deploy keys and the base permission, `account` for invitations to you. |
| 327 | |
| 328 | | Route | MCP tool and action | What it does | Who | |
| 329 | | --- | --- | --- | --- | |
| 330 | | `GET /repos/{owner}/{name}/collaborators` | `access` `list_collaborators` | Everyone with access to a repository, their role and where it comes from. | Write | |
| 331 | | `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 | |
| 332 | | `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 | |
| 333 | | `PATCH /repos/{owner}/{name}/collaborators/{username}` | `access` `update_collaborator` | Change someone's role, or a pending invitation's. Body: `role`. | Admin | |
| 334 | | `DELETE /repos/{owner}/{name}/collaborators/{username}` | `access` `remove_collaborator` | Take away the role given to someone on the repository. | Admin, or yourself | |
| 335 | | `GET /repos/{owner}/{name}/invitations` | `access` `list_invitations` | A repository's pending invitations. | Admin | |
| 336 | | `DELETE /repos/{owner}/{name}/invitations/{id}` | `access` `revoke_invitation` | Withdraw a pending invitation. | Admin | |
| 337 | | `GET /user/repository_invitations` | `account` `list_repository_invitations` | The invitations waiting for you. | You | |
| 338 | | `PATCH /user/repository_invitations/{id}` | `account` `accept_repository_invitation` | Accept one. | You | |
| 339 | | `DELETE /user/repository_invitations/{id}` | `account` `decline_repository_invitation` | Decline one. | You | |
| 340 | | `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 | |
| 341 | | `GET /workspaces/{workspace}/outside_collaborators` | `access` `list_outside_collaborators` | A workspace's outside collaborators and the repositories each can reach. | Owners | |
| 342 | | `GET /repos/{owner}/{name}/keys` | `access` `list_deploy_keys` | A repository's [deploy keys](/guides/git/#deploy-keys). | Admin | |
| 343 | | `GET /repos/{owner}/{name}/keys/{id}` | `access` `get_deploy_key` | One deploy key. | Admin | |
| 344 | | `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 | |
| 345 | | `DELETE /repos/{owner}/{name}/keys/{id}` | `access` `remove_deploy_key` | Delete a deploy key. | Admin | |
| 346 | |
| 347 | Changing who has access, answering an invitation and setting the base |
| 348 | permission are for people, signed in or with a personal access token. |
| 349 | |
| 350 | Roles are written `read`, `triage`, `write`, `maintain` and `admin`. |
| 351 | |
| 352 | ```sh |
| 353 | curl https://api.g1t.sh/repos/acme/rocket/collaborators/ada/permission \ |
| 354 | -H "Authorization: Bearer $G1T_TOKEN" |
| 355 | ``` |
| 356 | |
| 357 | ```json |
| 358 | { |
| 359 | "username": "ada", |
| 360 | "role": "write", |
| 361 | "source": "base", |
| 362 | "capabilities": ["read", "participate", "triage", "push", "merge", "manage_labels", "security_alerts", "run"] |
| 363 | } |
| 364 | ``` |
| 365 | |
| 366 | `source` is `owner`, `base`, `direct` or `team`. In the list from |
| 367 | `list_collaborators`, each person also has `direct`, the role given to them |
| 368 | on the repository if any, and `team_role` and `team`: the highest role a |
| 369 | team gives them there, and that team's slug. A team's own roles are managed |
| 370 | through the [teams API](/guides/teams/#through-the-api). |
| 371 | |
| 372 | ## Webhooks and the audit log |
| 373 | |
| 374 | A change to someone's role on a repository is sent to |
| 375 | [webhooks](/guides/webhooks/) as one of: |
| 376 | |
| 377 | | Event | When | |
| 378 | | --- | --- | |
| 379 | | `repo.collaborator_added` | Someone was given a role on the repository, or accepted an invitation. | |
| 380 | | `repo.collaborator_role_changed` | Their role changed. `data.role` and `data.previous_role`. | |
| 381 | | `repo.collaborator_removed` | Their role was taken away. | |
| 382 | |
| 383 | Each has `data.username`, `data.role` and `data.previous_role`. |
| 384 | |
| 385 | The workspace's [audit log](/guides/audit-log/) records the same changes |
| 386 | under those names, and also `repo.invitation_created`, |
| 387 | `repo.invitation_revoked`, `workspace.base_permission_changed`, and |
| 388 | `repo.deploy_key_added` and `repo.deploy_key_removed` for |
| 389 | [deploy keys](#deploy-keys). A repository's creator being given Admin is |
| 390 | not recorded: it comes with `repo.created`. |
| 391 | |
| 392 | A team's role on a repository changing is sent as `team.repo_added`, |
| 393 | `team.repo_role_changed` or `team.repo_removed`; see |
| 394 | [teams](/guides/teams/#webhooks-and-the-audit-log). |