# Roles and permissions

Who can read, push, merge and administer, for people, organization members, collaborators, signed-out visitors, tokens and agents.

## Check what you can do

```sh
sailfork whoami
sailfork org list
```

`whoami` shows your token's scopes and the repositories it is limited to. `org list` shows your role in each organization. A repository you cannot read answers 404, never 403, so its existence stays private.

## The model in one paragraph

Access to a repository is one of four levels: none, Read, Write or Admin. Where the level comes from depends on who owns the repository. On top of the level, a token carries scopes that can only narrow what you may do. A signed-out visitor has no level and reads public repositories only.

## Where a level comes from

| Repository | Who | Level |
| --- | --- | --- |
| Personal | The owner | Admin |
| Personal | A collaborator | Read or Write, as invited |
| Personal | Anyone else | None (Read for a public repository) |
| Organization | An organization Owner | Admin on every repository |
| Organization | A Member | The higher of the organization's base access and every team grant, including a parent team's |
| Organization | Anyone else | None (Read for a public repository) |

Organization roles are Owner and Member. There is no third role. Base access, teams and collaborators are explained below.

### Base access and teams

An owner sets Base access for members in Settings, Security and audit log, under Repository access: No access, Read or Write. It applies to every private repository in the organization for every member.

- **No access.** Members see public repositories, and a private one only when a team gives access to it.
- **Read.** Members read and clone every private repository. They push only where a team gives Write.
- **Write.** Members push branches to every private repository.

A team grant is Read, Write or Admin on a named repository. A child team inherits its parent's repositories. A grant can raise a member above base access. It never lowers them. Only owners create teams and grant repositories. A team's maintainers can add and remove its members. See [Organizations](https://sailfork.com/docs/organizations#teams).

### Collaborators on personal repositories

A repository that belongs to a person, not an organization, gives access through collaborators. Its admins invite someone by handle in the repository's settings, under Collaborators, choosing Read or Write. The person gets access when they accept. An invitation expires after 7 days.

An organization's repositories reject collaborators with `an organization's repositories give access through teams`.

### A second step can lock members out

An owner can require a passkey or authenticator for every member. A member without one gets level none on every organization repository, and every organization route refuses them with `acme requires two-factor authentication: add a passkey or an authenticator app in Settings, Security to get back in`. The rule applies to owners too.

## What each level allows

| Action | Needs |
| --- | --- |
| Browse, clone and fetch a public repository | Nothing, not even an account |
| Browse, clone and fetch a private repository | Read |
| Open an issue or pull request, comment, reply on a thread, add a review comment, react | Read, signed in, and not blocked |
| Open a pull request from your own `contrib/<handle>/` branch in a public repository | Read, signed in, and not blocked |
| Edit your own issue's title or body, close or reopen it | You are its author |
| Edit, close or reopen your own pull request | You are its author |
| Push a branch | Write |
| Approve or request changes, merge, resolve a thread | Write, and not the pull request's author |
| Change an issue's stage, owner, labels, priority, estimate, due date, milestone or relations, claim an issue | Write |
| Edit, close or reopen anyone's pull request or issue | Write |
| Publish, edit or delete releases and upload release assets | Write |
| Run, rerun or cancel CI, approve a deploy, delete a CI cache | Write |
| Open a caisson, write to it, commit, open its pull request, stop it | Write |
| See a caisson | Read |
| Change repository settings: description, visibility, default branch | Admin |
| Change branch protection, protected paths, release rules, the merge queue and merge rules | Admin |
| Push directly to a branch that requires pull requests | Admin |
| Add or change CI secrets and environments | Admin |
| Manage webhooks and mirrors | Admin |
| Invite or remove collaborators on a personal repository | Admin |
| Transfer a repository, delete it or restore it | Admin |

A signed-in person with Read can propose a change to a public repository without Write. They push a branch named `contrib/<their handle>/<name>` and open a pull request from it. Git refuses a push to any other branch with `you can only push to contrib/<handle>/ here: push your branch as contrib/<handle>/<name>, then open a pull request from it`. A contributor can have 20 such branches per repository.

An approval of a pull request you opened is a self-review: it is recorded and labeled, but never counts toward the approvals the merge rules ask for. Nobody can push to a pull mirror: the push fails with `this repository is a mirror of <remote> and is read-only: push there instead`.

### What only organization owners can do

| Action | Who |
| --- | --- |
| Invite people, revoke invitations, change roles, remove members | Owners |
| Create and delete teams, grant teams repositories | Owners |
| Change the organization's profile, base access, default visibility, second-step requirement and handle | Owners |
| Set the organization's merge rules | Owners |
| Add or remove verified domains | Owners |
| Connect the CI provider | Owners |
| Register Drydock hosts | Owners |
| Read the audit log, block people from the organization's repositories | Owners |
| See the organization's usage, change its plan, open billing | Owners |
| Schedule the organization for deletion | Owners |
| Change the organization's caisson policy | Owners, in the browser |

Any member can list teams, read the organization's merge rules and leave.

## Public and private repositories

A public repository can be read by anyone. A private repository can be read only by people with a level of Read or more.

When you cannot read a private repository, the web app and the API answer 404, so nothing reveals it exists. Over git, a request with no credentials gets 401 so git asks for them, and a request with valid credentials but no access gets 404 and `repository not found`.

An owner or admin switches a repository between public and private in its settings, under Visibility. An organization's New repositories start as setting picks the form's starting choice.

## What a signed-out visitor sees

A visitor who is not signed in can:

- browse code, history, issues, pull requests, releases and CI runs of public repositories, and clone them over HTTPS with no credentials,
- read an organization's page, which lists its public repositories and only the members who chose to be public.

A visitor cannot open issues, comment, react, push or see anything private. A private repository is a 404.

## Blocked people

You can block a person from your own repositories, and an organization owner can block people from the organization's repositories. Blocked people can still read public code, but cannot open or comment on issues and pull requests: `<owner> has blocked you, so you cannot open or comment on issues and pull requests here`. Organization members cannot be blocked. Manage blocks in Settings, Moderation, or the organization's Moderation page.

## How token scopes narrow a role

A token acts as you, and a scope can only remove abilities. Your access level and the token's scopes must both allow an action.

| What the token needs | For |
| --- | --- |
| `repo:read` | Reading a private repository over git or the API |
| `repo:write` | Pushing, opening and merging pull requests, editing issues, rerunning CI |
| `repo:admin` | Repository settings, branch protection, CI secrets, deleting a repository |
| `org:read` | Listing your organizations, members and teams |
| `org:admin` | Managing members, invitations, teams, merge rules, domains, CI providers and Drydock hosts |
| `sandbox` | Starting sandboxes and running commands on Drydock hosts |
| `user` | Your profile, SSH keys and tokens |

A token without the scope gets 403 `insufficient_scope: this token needs repo:write`. A token that has `org:admin` still cannot manage an organization where you are only a Member, because your role does not allow it.

A token limited to certain repositories answers 403 everywhere else. A token without `repo:read` can still fetch public repositories, as anyone can.

Some actions never work with a token. They need a browser session, and a token gets `this action needs a browser session, not a token`: signing out sessions, passkeys, the authenticator and recovery codes, adding or changing email addresses, deleting an account, exporting your data, changing a plan, transferring a repository, deleting an organization. Scopes are in [Access tokens](https://sailfork.com/docs/tokens#scopes).

## What agents can and cannot do

An agent is a token, a CLI login or an MCP connection that acts as the account that owns it. It has your access level and its token's scopes, and Sailfork labels its work when the tool names itself. In particular:

- **Same account, same limits.** An agent that works as you can do what your level and its scopes allow. It cannot approve a pull request you opened, because you are the author.
- **Approvals count by account.** A pull request merges when it meets the merge rules: the required number of approvals from people with Write who are not the author, plus the other rules. Sailfork counts an approval by who gave it. It makes no separate check of whether an agent produced it. An approval from an agent working under a different account counts like any other. To keep agent work from approving itself, require a review under the caisson policy.
- **Held writes.** A write through a caisson to a path under an Ask me rule waits for a person. No token can allow it, so an agent cannot allow its own write. It exits with code 11.
- **Never rules.** A write to a path under a Never rule is refused, and so is anything outside the caisson's scope.
- **CI.** A workflow's `GITHUB_TOKEN` cannot approve a deploy. A person with Write access must.
- **Caisson policy.** An organization's caisson policy changes in the browser, not with a token.
- **Review before shipping.** The caisson policy can require a review of a caisson's code before its pull request opens and again before it merges. The choices are Off, Agent and Independent. Agent accepts a review by anyone with push access, including a fresh subagent under the opener's own account, and labels it a self-review. Independent needs a review from a different account.
- **Tracking.** In Settings, Keys and tokens, Track agent work labels work from your tokens as agent work. Turning it off makes your tokens read as you. Plan limits and review rules still apply.

See [Agents](https://sailfork.com/docs/agents) and [Caissons](https://sailfork.com/docs/caissons) for the agent workflow.

---

Every docs page: https://sailfork.com/llms.txt
