Skip to content

Agent permission model

What an agent's token can and cannot do, what needs a person, what is recorded and what can be undone, covering merging, purging, branch rules and the audit log.

An agent on Sailfork is a token acting as the account that owns it. It has no powers of its own. It can do what that account's access level allows, narrowed by the token's scopes, repositories, branches and paths, narrowed again by the organization's agent controls, with the same branch and merge rules as a person. This page answers the questions a security review asks first, then lists every control.

The short answers

Do token scopes limit purge and merge?

Yes, each by a scope of its own. repo:merge is needed to merge a pull request, turn on auto-merge, queue it or merge a stack. repo:purge (with repo:admin) is needed to ask for a repository purge. No other scope includes either one: repo:admin does not purge, and repo:write does not merge. A token without the scope gets 403 insufficient_scope.

An assistant connected through MCP never gets repo:purge, repo:admin or org:admin. At the consent step the person chooses read only or read and write, and with write three more choices, each off until chosen: run code in sandboxes, merge pull requests and publish sandbox previews. An app's installation token never carries repo:purge or sandbox:expose.

One exception to know about: a token made before repo:merge, repo:purge and sandbox:expose existed was given each of them if it could already do that. Check old tokens under Settings, Keys and tokens.

Is a person required to approve before an agent merges?

In an organization's repositories, yes by default. Under Agents in the organization's Security settings, Hold merges for a person is on. A token's merge, auto-merge or stack merge then answers 202 HELD FOR A PERSON and changes nothing until a person approves it in the browser. The answer carries the request's id, so the agent can wait for the decision with sailfork wait held <id> (MCP: wait with kind: "held") and then repeat the merge. An approval covers one request for that exact head commit and lasts 24 hours. See Held merges and previews.

Three limits on that answer:

  • An owner can turn the switch off, and it is per organization. A personal repository has no such setting, so there a token with repo:merge merges at once, as long as the merge rules allow it.
  • Browser sessions are never held, and neither is a workflow's GITHUB_TOKEN.
  • Separately from this hold, the merge rules still decide whether a pull request can merge at all. See Branch protection and merge rules.

Do branch protections apply to agents?

Yes. Branch rules are checked on every push over HTTPS and SSH, every branch delete and every merge, by whatever credential makes it, and a caisson's writes meet the same branch protection as a push. Merge rules (approvals from people, resolved threads, required checks, the merge queue) decide every merge, an agent's included. Two things differ for a token:

  • An admin skips only the Pull requests only rule, and a token acts as its owner, so an admin's token can push to a branch with that rule. The other rules still bind it, and so do the token's own branch limits. Give an agent token branches globs, or agent: true, to keep it off protected branches.
  • Merging past the merge queue or the code owners' approval takes a reason from a repository admin. A token cannot give one: the API answers 403 bypass_needs_person.

Is the audit log immutable?

It is append-only in the application, not tamper-evident. No route and no code path edits an audit row, and none deletes one except retention: an organization's or account's audit log is deleted after 730 days, the tool-call record after 180 days, unless a legal hold covers the row. Rows also go when the organization or account that owns the log is deleted. There is no signature or hash chain on the rows, and a person with direct access to the database could change them. Streaming the log to your own tools is not available yet, so export it on a schedule if you need a copy kept elsewhere. See What is recorded.

Can a purge be undone?

It depends on who asks. A purge asked for with an access token deletes nothing: the repository stays scheduled for deletion, hidden from readers, and the date moves to at least 30 days away, so a person can restore it. A purge from a browser session deletes at once and cannot be undone. Scheduling a repository for deletion, which a token can do with repo:admin, keeps everything for 14 days. See Undo, purge and deletion.

What an agent token is

CredentialMade byReachesLasts
Personal access tokenYou, in Settings or with sailfork token createWhat its scopes, repositories, branches and paths allow, in every organization you belong toUntil its expiry. The form sets one; the CLI sets none unless you pass --expires.
CLI loginsailfork auth login, named CLI on <hostname>Every scope unless you passed --scopes90 days
MCP connection (OAuth)The person approving the assistantRead, and with write the scopes the person chose, on the MCP endpoint only, for the repositories chosenAn access token lasts an hour and its refresh token 30 days
Installation tokenAn app, from its client secretOne installation's repositories, with the permissions the installation was grantedAn hour
GITHUB_TOKENA CI jobIts own repository, within the job's permissions:Until the job ends
Sandbox tokenA sandbox created with token: "inherit", or a test run that asks for itThe sandbox's repository only, with the creating token's repo:read and repo:write, branches and paths. Never sandbox, repo:merge, repo:admin or org:adminUntil the sandbox ends or expires, and no later than the creating token

An app's installation token only moves refs when the installation has contents: write, whatever its other permissions.

Identity is a label, not authentication

The CLI and the MCP server name the agent tool in X-Sailfork-Agent, an id for the run in X-Sailfork-Session and the route in X-Sailfork-Surface. The server uses them to label pull requests, comments, commits and the record of tool calls. Nothing is decided by them: a caller can send any name, so no limit keys on it. Every limit keys on the token. An installation token always speaks as its app. Turning off Track agent work in Settings makes your tokens read as you in labels, and changes no limit.

Limits on one token

LimitHow to set itWhat it does
Scopes--scopes, or the checkboxesA scope only removes abilities. repo:read, repo:write, repo:merge, repo:admin, repo:purge, org:read, org:admin, sandbox, sandbox:expose and user. See Access tokens.
Repositories--repos owner/name, or repos in the APIEvery other repository answers 403, and so do account routes. You must be able to read each one.
Branchesbranches globs in the API, or agent: true for agent/**The only refs the token may move, by push, web edit, merge, branch delete and caisson. Tags count as refs. Reads are unaffected, and a branch-limited token cannot make tokens.
Pathspaths globs in the APIThe token can only git push, and a push is refused when any new commit changes a file outside them.
Read onlyScopes without repo:write, the read-only MCP address or --read-only, or the organization's Read onlyReads work and writes are refused.
Expiry--expires, the form's choiceThe API answers 401 after it. A token can only make tokens that expire no later than itself.
Refusal by ageThe organization's Oldest token acceptedSee Organization controls.

A token never goes beyond its owner. If you lose write access to a repository, so does every token of yours.

Organization controls for agents

An owner sets these under Agents in the organization's Security settings, in the browser. A token cannot change them, whatever its scopes (PATCH /api/orgs/{org}/agent-policy). The server checks them on every token request that names the organization, its repositories, caissons or sandboxes, so a change applies from the next request. They do not affect browser sessions or a workflow's GITHUB_TOKEN. The change limits apply to every caisson write made with an access token in an organization's repositories. They do not apply to browser sessions, git pushes or personal repositories. Every change is written to the organization's audit log.

ControlAPI fieldEffect
Access tokens: read and write, read only, stoppedaccessRead only refuses every write, push, caisson edit and sandbox command by a token. Stopped refuses every token request that names the organization. Both answer 403 with the code agent_policy.
Oldest token acceptedmaxTokenDays (1 to 365, or null)A token made more than that many days ago is refused in this organization, whatever its own expiry. An MCP connection counts from the day it was connected.
Hold merges for a personholdMerges (default true)A token's merge, auto-merge and stack merge wait for a person.
Keep an approval when the head movesmergeApprovalFollowsPull (default false)Off, an approval covers only the head the person saw, so a rebase after a conflict asks again. On, an approved merge counts for any later head of the same pull request for 24 hours, so new commits merge without a second look. Either way, a declined merge stays declined for 24 hours on every head of that pull request, so a new commit cannot get around it.
Hold sandbox previews for a personholdPreviews (default true)A token's request to publish a sandbox port as a link waits for a person.
Monthly agent change limitmonthlyChangeCap (1 to 100,000,000, or null for none)Counts every caisson write made with an access token in the organization's repositories, labeled as an agent's or not. At the limit, those writes answer 402 agent_change_cap until an owner raises it. Owners get an inbox notice and an email at 80% and again at 100% of the month's limit.
Agent changes per minutechangesPerMinute (1 to 10,000, or null for none)Past that many such writes a minute in the organization, they answer 429 with Retry-After.
Agent pushes must be signedrequireSignedCommits (default false)A git push made with an access token is refused unless every new commit on every branch has an SSH signature from a verified signing key of the pusher or the author. SSH pushes use a person's own key and are not affected.

The three limits that live in an organization's other settings also apply to agents: merge rules, branch rules and rulesets and the caisson policy.

Held merges and previews

A merge and a sandbox preview cannot be undone, so they wait for a person when the organization holds them.

  1. The agent's request answers 202 with held, kind, summary and a message that starts HELD FOR A PERSON. Nothing has happened. The MCP tools and the CLI (exit code 11) tell the agent to stop and ask the user.
  2. People who can decide it get an inbox notice and an email. A merge is decided by someone with write access to the repository, the token's owner included. A preview is decided by a member of the organization.
  3. The person approves or declines under Agent requests in the sidebar, or on the pull request's own page for a merge (POST /api/held/{id}). A token is refused there, so an agent cannot answer its own request. The decision is written to the audit log.
  4. After an approval, the agent repeats the same request and it goes through once. The approval names the pull request's head commit, or the sandbox and port: a branch that moved after the approval is held again. It expires after 24 hours.
  5. After a decline, the same request answers 403 held_declined for 24 hours.

A merge into a repository that is not in an organization, a browser session and a GITHUB_TOKEN are not held. Auto-merge is held when it is turned on, and the later merge then runs as the person who turned it on, with their agent token's label.

Branch protection and merge rules

These are the same rules people meet. An agent does not get a separate set, and gets no exemption.

RuleFor an agent's token
Pull requests onlyApplies unless the token's owner is a repository admin. Use a token's branch limit to cover that case.
Block force pushes, block deletionApply to everyone.
Who may push, who may mergeApply to the token's owner. Admins are not exempt.
Signed commits, blocked secrets, verified emails, blocked extensions, largest fileChecked on every git push before any ref moves. They read pushes, not caisson commits.
Approvals from peopleA pull request needs approvals from people who are not its author. An approval counts by the account that gave it, so a token of another person's account counts as that person. An app's bot counts only where the repository trusts that app.
Required checks, resolved threads, up to dateDecide every merge.
Merge queue, code owners' approvalApply. Merging past them takes an admin's reason, and a token cannot give one (403 bypass_needs_person).
A pull request that adds a database migrationNeeds a person's approval.

The branch limit agent/** is the simplest way to keep an agent token off every branch outside agent/. See Branches and protection.

Caissons

A caisson is where an agent edits code on the server. Writes through it are checked before they land.

  • Path rules. The repository's owner (you, or the organization) marks paths as Ask me or Never. A path with no rule is allowed. A write under a Never rule is refused with a 403 that names the rule. Some rules are fixed: migrations/** always asks and .sailfork/** is always never.
  • Held writes. A write under an Ask me rule answers 202, the caisson moves to waiting, and the write lands only when a person approves it in the browser. No token can approve one.
  • Scope. A caisson takes 1 to 50 path entries, and a write outside them is refused.
  • Review before shipping. The caisson policy can require a review of the exact code before the pull request opens and again before it merges.
  • Signed commits. A commit made from a caisson is signed by the server with an SSH signature. You stay the author and committer, and the message ends with Sailfork-Caisson, and, when they apply, Sailfork-Token (the token's name and id) and Sailfork-Agent trailers that the signature covers. Anyone can check one against the public key at /.well-known/sailfork/allowed_signers. See Caissons.
  • Lockdown. The MCP server hides what people without push access wrote from the model: titles, bodies and comments on issues and pull requests, where a prompt injection would sit. It is on by default for public repositories and off for private ones. ?lockdown=on extends it to every repository and ?lockdown=off turns it off. It applies to what the model reads through MCP tools, not to the REST API.

What is recorded

RecordWhat it holdsWho reads itKept
Tool-call recordOne row per API request an access token made under an MCP tool: the tool, the route without its query string, the status, the repository, the client and session. Never the arguments.An organization's owners for its repositories (GET /api/orgs/{org}/audit/tool-calls, and an NDJSON export), and you for your own calls (GET /api/me/audit/tool-calls)180 days
Organization audit logChanges to members, rules, access, the agent controls, held-request decisions, merges past a rule, repository deletions and purges, with the actor and whether an agent did itThe organization's owners, in the browser or over the API with org:read, and as an NDJSON export730 days
Your audit logModeration and access changes on your personal repositoriesYou730 days
Security logYour sign-ins, SSH key and token creation and useYou2 years

Two things the record does not cover. An ordinary action by an agent, such as a comment or a push, is not an audit event: it shows as the work itself, labeled as agent work, and in the tool-call record when it came through an MCP tool. And a request made with a token by the CLI or the REST API rather than an MCP tool carries no tool name, so it is not in the tool-call record.

The tool-call record is written after the response, never blocks a request and is skipped for browser sessions and GITHUB_TOKEN runs. When the account turned off agent tracking, its rows keep the tool and the route and leave the client, session and surface empty.

Immutability, exactly: the application inserts audit rows and reads them. The only code that deletes them is the hourly retention job, which skips rows under a legal hold, and the cascade that removes an organization's or account's rows when it is deleted. A deleted account's handle stays in an organization's log, as the log's actor name. Nothing signs the rows, and the database itself is not append-only, so a log is only as trustworthy as the access to that database.

Undo, purge and deletion

ActionHow long it can be reversedBy whom
Many agent actions: an issue or pull request comment, an issue or pull request update, a pull request merge, a caisson file delete, a branch delete, a token created24 hours, once (sailfork undo). A merge undoes only while the base has not moved past it.The account the agent acted as
Scheduling a repository for deletion (repo:admin)14 days: restore it in Settings, or with DELETE /api/repos/{owner}/{repo}/deletion. Once the purge has started it cannot be cancelled.A repository admin
Purge asked for with an access token (repo:admin and repo:purge)30 days. The repository stays scheduled and hidden, and the hourly job deletes it no sooner than 30 days after the request.A repository admin, in the browser or with a token
Purge from a browser sessionNot at all: the repository's data and row are deleted at once.
Held write, merge or previewNot applied until approved, so nothing to undo.

A repository under a legal hold cannot be purged, and a repository with forks is purged only after they are gone.

What a token can never do

Some actions need a browser session whatever the token's scopes: approving or declining a held write, merge or preview, changing the caisson policy or the organization's agent controls, merging past the merge queue or code owners' approval, signing sessions out, passkeys and recovery codes, changing an email address, deleting an account or an organization, transferring a repository, changing a plan and exporting your data. See Roles and permissions.

Loading Sailfork