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

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

RepositoryWhoLevel
PersonalThe ownerAdmin
PersonalA collaboratorRead or Write, as invited
PersonalAnyone elseNone (Read for a public repository)
OrganizationAn organization OwnerAdmin on every repository
OrganizationA MemberThe higher of the organization's base access and every team grant, including a parent team's
OrganizationAnyone elseNone (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.

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

ActionNeeds
Browse, clone and fetch a public repositoryNothing, not even an account
Browse, clone and fetch a private repositoryRead
Open an issue or pull request, comment, reply on a thread, add a review comment, reactRead, signed in, and not blocked
Open a pull request from your own contrib/<handle>/ branch in a public repositoryRead, signed in, and not blocked
Edit your own issue's title or body, close or reopen itYou are its author
Edit, close or reopen your own pull requestYou are its author
Push a branchWrite
Approve or request changes, merge, resolve a threadWrite, and not the pull request's author
Change an issue's stage, owner, labels, priority, estimate, due date, milestone or relations, claim an issueWrite
Edit, close or reopen anyone's pull request or issueWrite
Publish, edit or delete releases and upload release assetsWrite
Run, rerun or cancel CI, approve a deploy, delete a CI cacheWrite
Open a caisson, write to it, commit, open its pull request, stop itWrite
See a caissonRead
Change repository settings: description, visibility, default branchAdmin
Change branch protection, protected paths, release rules, the merge queue and merge rulesAdmin
Push directly to a branch that requires pull requestsAdmin
Add or change CI secrets and environmentsAdmin
Manage webhooks and mirrorsAdmin
Invite or remove collaborators on a personal repositoryAdmin
Transfer a repository, delete it or restore itAdmin

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

ActionWho
Invite people, revoke invitations, change roles, remove membersOwners
Create and delete teams, grant teams repositoriesOwners
Change the organization's profile, base access, default visibility, second-step requirement and handleOwners
Set the organization's merge rulesOwners
Add or remove verified domainsOwners
Connect the CI providerOwners
Register Drydock hostsOwners
Read the audit log, block people from the organization's repositoriesOwners
See the organization's usage, change its plan, open billingOwners
Schedule the organization for deletionOwners
Change the organization's caisson policyOwners, 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 needsFor
repo:readReading a private repository over git or the API
repo:writePushing, opening and merging pull requests, editing issues, rerunning CI
repo:adminRepository settings, branch protection, CI secrets, deleting a repository
org:readListing your organizations, members and teams
org:adminManaging members, invitations, teams, merge rules, domains, CI providers and Drydock hosts
sandboxStarting sandboxes and running commands on Drydock hosts
userYour 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.

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 and Caissons for the agent workflow.

Loading Sailfork