Branches and protection
List and delete branches, keep the default branch safe, and set the rules a pull request must meet before it merges, including branch rules, required checks, owners, protected paths, the merge queue and tag protection.
List and delete branches
sailfork branch list
sailfork branch delete feat/login --dry-run
sailfork branch delete feat/login --yes branch list shows the repository's branches with the default one first. branch delete removes one. It asks first on a terminal, and needs --yes where there is none. --dry-run says what it would do and changes nothing. Inside a clone, the repository comes from the git remote. Elsewhere add -R owner/repo. git push origin --delete feat/login does the same thing.
Deleting needs push access. These stay:
- The default branch. It answers
<name> is the default branch; make another branch the default before deleting it. Change the default first, under Settings, General, Default branch. - A protected branch. A branch rule that blocks deletion refuses it with
<name> is a protected branch and cannot be deleted. - Any branch of a pull mirror, whose branches follow the remote.
A branch that moved while you were deleting it answers 409 and nothing is deleted.
The Branches screen
Open Branches on a repository. It groups every branch:
| Group | What is in it |
|---|---|
| Protected | The default branch, with the merge rules that apply to it. It takes merges only. |
| Active | Pushed in the last 30 days. |
| Stale | No push in 30 days. Deleting one loses the commits only it has. |
| Merged | Everything on it is already in the default branch, so deleting it loses nothing. |
Each row shows who pushed last (agents are named as such), when, the subject of that commit, how many commits it is ahead of and behind the default branch, its pull request, and the latest CI run. A branch with commits and no pull request shows Open pull request. People who can write see Delete on a row. For a branch that is ahead, the button says how many commits you would lose before you confirm. A group of merged branches also has Delete all N.
Use the Everyone, People and Agents switch to see who made each branch, and Find a branch or owner to search. An agent's caisson works on a branch named caisson/<id>. Outside contributors' branches (contrib/<handle>/...) stay out of this list.
The default branch's panel states the rules in force, such as 2 people approve every pull request. With none set it says No merge rules yet, so anyone with write access can merge, with a link to set them.
Merge rules
Merge rules decide when a pull request may merge into a branch. Five settings apply to every pull request in a repository:
| Rule | Meaning |
|---|---|
| Approvals from people | How many people, not the author, must have a latest review that approves. The API accepts 0 to 6. An agent's approval never counts. |
| Dismiss stale approvals | A push to the branch after an approval voids it. |
| Up to date with the base | The branch contains the base branch's tip. |
| Threads resolved | Every comment thread on the changes is resolved. |
| Author self-review | The author approves their own pull request first, for when an agent wrote it. It never counts toward the approvals. |
A repository takes its organization's rules unless it has its own. Organization owners set theirs under Merge rules in the organization's settings (https://status.sailfork.com/<org>/settings/merging), where the page also dry-runs them against open pull requests. A repository's own rules replace the organization's, and the repository settings screen will not let you set approvals below the organization's number.
In the web app, a repository admin sets Approvals from people under Settings, Merging. That screen also saves Author self-review and the apps whose approval counts. To set the other rules, call the API. Admins only, and the token needs repo:admin:
sailfork api /api/repos/fenil/ocean-landing/merge-rules --method PUT --input - <<'EOF'
{"approvals": 1, "dismissStale": true, "upToDate": false, "threadsResolved": true, "selfReview": false}
EOF DELETE on the same route removes the repository's own rules, so it follows the organization again.
What you see on a pull request
The pull request lists each condition and whether it holds: Marked ready, Checks pass, Approved by a person (or Approved by N people), No changes requested, Self-reviewed, Threads resolved, Up to date with main and conflicts with the base. A pull request that adds a database migration also needs a person's approval: a migration never merges without one. See Pull requests and Code review.
A merge that the rules refuse answers 409 with one message naming everything that is missing:
merge rules not met: needs 2 approvals and has 1; 1 comment thread is unresolved Branch protection rules
Branch rules are stored per repository and checked on every push over HTTPS and SSH, on deleting a branch and when a pull request merges. A repository admin sets them in the web app under Settings, Branch rules, or through the API. An organization's rulesets apply on top of a repository's own rules.
In the web app each rule starts with the branches it covers, a pattern like release/*, and the line under it lists the branches that match now. Add a branch rule starts another, and Save writes every change on the settings screen at once. With no rule the screen says No branch is protected: anyone who can push may force push or delete any branch.
| Control | API field | What it does |
|---|---|---|
| Pull requests only | requirePullRequest | Only repository admins push to the branches directly. Everyone else merges a pull request. |
| Block force pushes | blockForcePush | Only updates that descend from the old commit are accepted. |
| Block deletion | blockDeletion | The branch cannot be deleted, by a push or the API. A merged branch is kept too. |
| Owners approve | requireOwners | A pull request into the branches needs the approvals the OWNERS files ask for. |
| Who may push | pushPeople, pushTeams | Only these people and members of these teams push to the branches. Empty means everyone who can write. Admins are not exempt: they change the rule. |
| Who may merge | mergePeople, mergeTeams | Only these people and team members merge a pull request into the branches. Empty means everyone who can write. |
| Who can see these branches | readersPeople, readersTeams | Set anyone here and the matching branches become private. Only these people, these teams (child teams included) and the repository admins can fetch, clone, browse or search them. Repository rules only. |
| Required checks | requiredChecks | CI checks that must pass before a pull request merges into the branches. See Required checks. |
Teams are organization teams, so a personal repository has people lists only. A listed person or team member also needs write access to count. A handle or team that does not exist is refused with 422, as <pattern>: no user <handle> or <pattern>: no team <slug>.
The same screen has Keep contributors' branches private (privateContributions). When it is on, a contrib/<handle>/ branch is visible only to the person who pushed it and the repository admins. A pull request opened from one stays visible to everyone who can read the repository.
Each rule also checks what a push contains. The server reads a push while it receives it, before any branch moves, and a refusal names the rule, the commit, the file and the line.
| Control | content field | What it refuses |
|---|---|---|
| Block secrets | secrets | Text shaped like a credential: private keys, cloud and API tokens, passwords in URLs. |
| Signed commits | signedCommits | A new commit without an SSH signature from a verified signing key of the pusher or the author. A GPG signature cannot be verified here and is refused. |
| Verified author emails | verifiedEmail | A new commit whose author email is not a verified address of the person pushing it. |
| Blocked paths | blockedPaths | A pushed file that matches one of the globs. ** crosses folders. |
| Blocked extensions | blockedExtensions | A pushed file with one of these extensions, written without the dot, like pem. |
| Largest file | maxFileBytes | A pushed file over this many bytes. The screen takes megabytes. |
To set rules from a script, PUT the whole list. It replaces every rule, allows at most 50, and needs a repository admin with the repo:admin scope. GET on the route reads them back.
To apply the same rules to many repositories of an organization, see Rulesets.
sailfork api /api/repos/fenil/ocean-landing/branch-protections --method PUT --input - <<'EOF'
{"rules": [
{"pattern": "main", "blockForcePush": true, "blockDeletion": true, "requirePullRequest": true, "requiredChecks": ["test"]},
{"pattern": "release/*", "blockForcePush": true, "blockDeletion": true, "requirePullRequest": false,
"pushTeams": ["release"], "content": {"secrets": true, "signedCommits": true}}
]}
EOF The pattern is a glob over the branch name, with no refs/heads/ prefix. * stops at /, so release/* matches release/1.0 but not release/1.0/hotfix. ** crosses /. It is 1 to 200 characters, and listing one twice is refused.
Every rule whose pattern matches a branch applies. Each refused branch in a push is reported on its own, and git prints ! [remote rejected] main -> main (reason). The push's other branches still go through.
| Reason | Cause |
|---|---|
protected branch: force push is not allowed | An update that does not descend from the old commit. |
protected branch: deleting it is not allowed | A delete of a branch with blockDeletion. |
protected branch: changes to <branch> must go through a pull request | Any create, update or delete by someone who is not a repository admin. |
protected branch: only <people and teams> may push to <branch> | A push by someone who is not on the rule's push list. |
protected branch: only <people and teams> may merge into <branch> | A pull request merged by someone who is not on the rule's merge list. |
Required checks
A name in requiredChecks is a workflow name, which holds when the latest run of that workflow on the pull request's head commit passed, or a job name or id, which holds when that job passed in the latest run of its workflow. It can also name a check run an app or another CI provider reports, which holds when the newest run of that name passed. Pushes are not checked. Only merges are. A merge that is missing one answers merge rules not met: required check <name> failed on <sha>, or says it has not finished or has not run. Checks come from CI and check runs.
Protected paths
A protected path needs a specific reviewer for any change to files that match it. In the web app, Settings, Protected paths lists them, but that group does not load or save yet: it starts empty, and Save does not write it. Set protected paths through the API.
sailfork api /api/repos/fenil/ocean-landing/protected-paths --method PUT --input - <<'EOF'
{"paths": [{"glob": "db/migrations/**", "teams": ["platform"], "people": ["fenil"], "locked": false}]}
EOF Each path names organization team slugs and people's handles. At most 100 paths. When a pull request merges, each file it changes is matched against the paths in order, and the first path that matches needs an approval from one of its people or from a member of one of its teams. Otherwise the merge is refused with merge rules not met: <glob> needs an approval from team <team> or @<handle>. A direct commit from the web editor to a file under a protected path is refused too. Committing to a new branch and opening a pull request is the way through. locked only changes what the settings page shows. The server ignores it.
When a branch rule has Owners approve on, protected paths get stricter for pull requests into those branches: an approval counts only from a listed person or team member with write access (child teams included), and a push that changes a protected path is refused unless the pusher is one of its owners. The refusal reads ... needs an approval from ... on a merge, and owned path: <file> is covered by <rule> and needs an owner from ...; open a pull request on a push.
Owners files
An OWNERS file says who must approve changes to the files beside it. The Owners tab on a repository (https://status.sailfork.com/<owner>/<repo>/owners) and the Owners group in settings read these files from the default branch, or from ?ref=<branch> on the tab. They list each file with its rules, and warn about an owner who has no write access (no write access, their approval does not count), a team that does not exist (no such team), and lines the server could not read (Line 3: ...). Edit the files in the repository like any other file.
Owners apply only to pull requests into a branch whose rule has Owners approve on. With it off, OWNERS files are ignored.
An OWNERS file sits in a folder and governs that folder and everything below it. One line is one rule, and # starts a comment:
set noparent # ignore the OWNERS files of the folders above
fallback @alice # owners of files in this tree that no rule below matches
web/** @bob @acme/web-team approvals=2
docs/** @carol light=anyone | Part | Meaning |
|---|---|
| Glob | Matched against the path relative to the file's folder. * stays inside one folder, ** crosses folders, ? is one character, and [ab] is a set. *.rs covers only the top folder and **/*.rs every folder. |
@handle | A person. |
@org/team | A team of the repository's organization, child teams included. The organization must be the repository's own. |
approvals=N | How many owners must approve, 1 to 6. Default 1. |
light=owners or light=anyone | When every changed file the rule covers only changes comments or formatting, one owner (owners) or one person with write access (anyone) is enough. One code change puts the full rule back. |
fallback @x | The rule for files in the tree that no other rule matches. |
set noparent | Stop looking at the OWNERS files in the folders above. |
A rule needs at least one owner. A bad line is skipped and shown on the Owners tab. A file holds at most 500 rules.
For each changed file, the nearest OWNERS file with a matching rule (or a fallback) names the rule that applies. Within one file the last matching rule wins. The owners of rules further up the tree also count as approvers, until a file says set noparent. Only owners with write access to the repository can approve, and an approval from the author never counts.
The files are read from the base branch of the pull request, never from the pull request's own commits, so a pull request cannot change who must approve it. A change to OWNERS goes through review like any other file. A change that touches more than 2000 folders cannot be checked, and the message asks you to split the pull request.
A direct push to a branch with Owners approve on may change an owned path only when the pusher is an owner of it and the rule needs one approval. Everyone else, admins included, opens a pull request.
Merge queue
The merge queue lands pull requests on the default branch one batch at a time, so they stop racing each other to rebase. Turn it on under Settings, Merge queue, with Use a merge queue. Admins only.
| Setting | API field | What it does |
|---|---|---|
| Use a merge queue | on | The default branch takes merges only from the queue. Each pull request merges on its own when this is off. |
| Batch size | batch | How many ready pull requests land together, 1 to 10. Default 1. |
| Batches in flight | maxInFlight | How many landed batches may still be untested at once, 1 to 32. Default 4. The queue waits for CI to catch up past this. |
| Rerun flaky checks | recheck | When a batch's checks fail, its failed jobs run once more before the queue looks for the pull request that broke it. |
| Longest wait | maxWaitMinutes | 1 to 120 minutes. Stored, but the queue does not use it yet. |
| Agents queue their own approved pull requests | autoEnqueueAgents | Stored, but the queue does not use it yet. Someone with write access still queues an agent's pull request. |
With the queue on, a merge into the default branch goes through it. A direct merge is refused with a message that names sailfork pr merge <number> --auto. A repository admin can merge past it with a reason, sailfork pr merge 12 --bypass-queue "outage fix", and the reason goes to the audit log as merge_queue.bypass.
Someone with write access queues a pull request with sailfork pr merge 12 --auto or by setting it to merge when ready in the web app. The queue lands each pull request that meets the merge rules, in the order they were queued, as the person who queued it and with the head they reviewed. sailfork queue status shows what is waiting, the batches being tested and what left the queue lately with why. sailfork queue leave 12 takes one out.
A stack queues as one unit: the pull requests that are stacked on each other land together, bottom first, in one batch, and the ones above the bottom wait for the one below. See Pull requests.
Each batch is tested like any push to the default branch. A tip that shows no check at all for 10 minutes counts as tested. When a batch fails:
- Nothing more lands. With Rerun flaky checks on, the failed jobs run once more first.
- If it fails again, the queue searches the landings since the last good tip for the first one that fails, and tells whoever queued it.
- The queue lands a revert of that pull request through an ordinary pull request, as the person who queued it, and tests the revert before anything else lands.
When the revert cannot land, for example because it conflicts with later work, the batch stays failed with the reason in its note and a person takes over. The queue does not land anything until that batch is resolved.
sailfork api /api/repos/fenil/ocean-landing/merge-queue --method PUT --input - <<'EOF'
{"on": true, "batch": 3, "maxWaitMinutes": 10, "recheck": true, "autoEnqueueAgents": false, "maxInFlight": 4}
EOF Tag protection
Tag rules decide who creates a tag and whether an existing tag may move. They are checked on every push, and are off until Protect tags is on under Settings, Tags.
| Setting | API field | What it does |
|---|---|---|
| Protect tags | enforce | Turns the rules below on. Off, anyone who can write creates, moves or deletes tags. |
| Who may create tags | pushTeam | Members of this team, child teams included, create tags. None picked means everyone who can write. Organization repositories only. |
| Also may create tags | tagsCreatedBy | Members of this second team create tags too. workflow means no other team. Organization repositories only. |
| Tags may move | forcePush | Allows moving or deleting an existing tag. Off keeps every published tag where it is. |
A refused push answers protected tags: only the release team may push tags, so <tag> was not pushed, or protected tag: <tag> already exists and cannot be moved or deleted. Admins are not exempt. The screen also shows whether a branch rule blocks force pushes to the default branch.
sailfork api /api/repos/acme/site/release-rules --method PUT --input - <<'EOF'
{"enforce": true, "pushTeam": "release", "tagsCreatedBy": "workflow", "forcePush": false}
EOF PUT replaces the whole value, so send enforce, pushTeam, tagsCreatedBy and forcePush every time. The approvals field is kept and returned but nothing uses it: no rule asks a release for approvals.
Projects
Settings, Projects has a place to list the folders of a monorepo with an owning team and checks for each. It does not do anything yet. The server has no setting behind it, the group does not load or save, and Save never writes it. Until then, use protected paths or OWNERS files to make a team review its folders, and required checks to name the checks a branch needs.
Settings the server stores but does not use
| Setting | What happens |
|---|---|
Merge queue Longest wait (maxWaitMinutes) | Kept and returned. The queue does not read it. |
Merge queue Agents queue their own approved pull requests (autoEnqueueAgents) | Kept and returned. The queue does not read it. |
Tag rules approvals | Kept and returned. Nothing asks a release for approvals. |
Protected path locked | Only changes what the settings page shows. |
| Web Protected paths and Projects groups | Not loaded and not saved. Protected paths are set through the API. Projects has no server setting. |
After a merge
sailfork pr merge deletes the pull request's branch after the merge unless a rule keeps it. Pass --keep-branch to keep it.
Who can do what
| To do this | You need |
|---|---|
| List branches | Read access. Anyone, on a public repository. |
| Delete a branch | Push access, and the branch is not the default or protected. |
| Set merge rules, branch rules, protected paths, the merge queue or tag rules for a repository | Repository admin, and a token with repo:admin. |
| Queue a pull request | Push access. |
| Set an organization's merge rules | Organization owner. |
See Permissions for how access levels work.