Pull requests

Open a pull request, follow its checks and reviews, and merge it from the web app, the CLI or a script.

Open one and merge it

Push a branch, open the pull request, wait for CI, then merge.

git push -u origin fix/tide-math
sailfork pr create --fill
sailfork pr checks --watch
sailfork pr merge --method squash

pr create pushes the current branch first and opens a pull request into the repository's default branch. --fill takes the title and description from your commits and never opens an editor. The other sailfork pr commands default to the open pull request for the branch you have checked out, so they need no number. Add -R fenil/ocean-landing to act on a repository from outside a clone.

Open a pull request

In the web app

Open the repository's Pull requests page and choose New pull request, or go to /fenil/ocean-landing/pulls/new?head=fix/tide-math. On the compare page:

  1. Pick the From branch (your changes) and the Merge into branch. The page says "Pick two different branches." until they differ. Swap the branches flips them.
  2. Read the line under the pickers: "Merges cleanly." or the list of conflicting files.
  3. Write a Title and a Description.
  4. Check Open as a draft if you want to hold it back, then choose Create pull request (or Create draft pull request).

From the CLI

sailfork pr create --title "Fix the tide math" --body-file notes.md
sailfork pr create --fill --draft --reviewer ada
sailfork pr create --fill --base release --closes 7
FlagWhat it does
-t, --title, -b, --body, --body-file <FILE>Set the title and description. --body-file - reads stdin.
--fillTake both from the commits.
--base <BRANCH>Branch to merge into. Default: the repository's default branch.
--head <BRANCH>Branch with the changes. Default: the current branch.
--draftOpen it as a draft.
--reviewer <HANDLE>Ask one person to review it.
--issue <N>, --closes <N>Link an issue (repeatable). See Link issues.
--no-pushDo not push first. Fails if the branch is not on the server.

From a caisson

A caisson opens its pull request for you. sailfork cs pr <id> opens it, and sailfork cs ship <id> -m "message" --closes 7 commits and opens it in one step. See Caissons.

The pull request page

The page is one scroll with these parts:

  • What and why: the description, and "Closes #7" when an issue is linked.
  • Caisson: shown when a caisson worked on the branch.
  • Checks: the CI jobs of the newest run of each workflow on the head commit. A summary pill at the top jumps here and links the failing run.
  • Changes: the diff, as Unified or Split. Large and generated files are folded.
  • Conversation: comments, review summaries and the commits, in time order.

The merge panel sits beside the page on a wide screen and under the header on a narrow one. The header has Edit (title and description), Ready for review, Back to draft, Close, Reopen, Lock conversation and Browse code. The author and anyone with push access see the edit actions.

sailfork pr view prints the same facts, and sailfork pr diff prints the diff. --summary shortens either: no body or comments for view, a per-file stat for diff.

Drafts

A draft is a pull request that is not ready for review. The merge panel holds it back ("Still a draft") until the author marks it ready.

sailfork pr create --fill --draft
sailfork pr ready 12
sailfork pr draft 12

In the web app the same moves are Ready for review and Back to draft in the header.

Update a branch

Push more commits to the head branch and the pull request follows. If the base branch moved on, bring it in without a local checkout:

sailfork pr update-branch 12

The server merges the base into the head branch with a commit named Merge branch '<base>' into <branch>. In the web app this is the Bring in main button in the merge panel, shown when the branch is behind and nothing conflicts. The author and anyone with push access can use it, on an open or draft pull request. It answers 409 and names the files when the branches conflict, and when a branch rule refuses the push. Run git pull afterward to get the new commit.

Stacked pull requests

A stack is a chain of pull requests where each one is based on the branch of the one below it. Use one to split a large change into pieces that are reviewed and merged one at a time. Each pull request shows only its own commits and its own diff.

git switch -c feat/schema
sailfork pr create --fill
git switch -c feat/api
sailfork pr create --fill --onto 12
sailfork pr stack
sailfork pr merge 13 --stack

--onto 12 takes the head branch of pull request 12 as the base. It conflicts with --base, and pull request 12 must be open or draft (#12 is merged: stack only on an open or draft pull request). Move an existing open or draft pull request with sailfork pr edit 13 --onto 12, or back onto a branch with --base <BRANCH>.

sailfork pr stack [N] prints the whole stack that pull request N belongs to, root first, indented by depth, one row per pull request with its state, checks, review, title and branches. <- this marks N. Add --json for scripts.

WhatBehavior
PageA pull request in a stack shows a Stack section with the tree and a View graph link to the work graph. The merge panel says where merging lands, for example that it merges into the branch of the pull request below, not into main.
ReviewEach pull request is reviewed, checked and held by the merge rules on its own.
Merge from the pageOn a stacked pull request, Merge the stack into main in the merge panel lands every open pull request below it and then this one, bottom first, each once its checks pass. It runs on the server, so you can close the page; the panel says which pull request it waits on and offers Cancel the stack merge on every level. A push to any level, or closing one, stops it. The API is PUT /api/repos/{owner}/{repo}/pulls/{n}/auto-merge with {"stack": true}.
Mergesailfork pr merge N --stack merges the open pull requests below N first, bottom-up, then N, each into the base of the bottom one. It stops at the first one that fails and names what merged and what did not. --dry-run prints the order and changes nothing.
WaitingA level above the first waits for its checks when its branch moved after the one below merged, or they are still running. --auto waits for every level.
After a mergeThe branch of the merged pull request is deleted, and each pull request stacked on it moves onto its base. After a squash or rebase, the server carries the branch over so the work below is not shown twice. A branch that does not carry over cleanly stays where it is: sailfork pr edit N --base <BRANCH> moves it.
Merge queueWhen the base takes merges through the merge queue, a stack waits in the queue as one unit and lands bottom first. A pull request above one that left the queue cannot land.

--stack cannot be used with --match-head-commit or --keep-branch, because each level follows the one below only when the branch below is deleted. A stack is followed up to 32 levels.

Agents read a stack with the pull_stack tool of the MCP server, and pr create and pr edit take onto there too.

An issue is linked in any of three ways:

  • The description says closes #7, fixes #7 or resolves #7.
  • sailfork pr create --issue 7 (alias --closes) adds Closes #7 for you.
  • The branch is named issue/7-fix-login, which is what sailfork issue start 7 creates.

Linking moves the issue to In review, and merging the pull request closes it. See Issues.

Merge

Choose Merge as in the merge panel (Merge, Squash or Rebase), decide whether to Delete the branch after merging, and press Merge into main. The panel explains each choice:

MethodResult
MergeThe base fast-forwards to the branch, or gets one merge commit when it has moved on.
SquashThe commits become one commit on the base, named after the pull request.
RebaseEach commit is replayed on top of the base, one by one, with no merge commit.
Fast-forward (CLI and API only)The base fast-forwards to the branch. Refused when the base has commits the branch lacks.

A rebase refuses a branch that contains merge commits ("merge or squash it instead of rebasing") and one that conflicts with the base.

sailfork pr merge 12 --method squash
sailfork pr merge 12 --dry-run
sailfork pr merge 12 --auto --method squash
sailfork pr merge 12 --match-head-commit 3f2a9c1
FlagWhat it does
--method <merge|squash|rebase|fast-forward>How the commits land. Default: fast-forward when the base has not moved, else a merge commit.
--dry-runCheck that it can merge and change nothing.
--autoMerge once the checks pass: the server waits and merges as you, only if the branch is still at the head you reviewed, and the command returns at once. --cancel-auto turns it off. With --stack the command waits for each level itself.
--match-head-commit <SHA>Merge only if the branch is still at this commit. Otherwise exit 10 and merge nothing.
--keep-branchKeep the head branch. By default the server deletes it, unless a branch protection keeps it.

Merging needs push access. When the repository has a merge queue on, --auto queues the pull request, and a direct merge into the default branch is refused. A pull request that is already merged answers with its current state when its branch has not moved, and 409 when the branch has new commits since.

Note

A pull request in a repository that mirrors another host is read-only here. The panel says "Reviews and merges happen on the original."

What blocks a merge

The merge panel lists each requirement as done, waiting or blocking, and the Merge into button stays off until none is left:

Item in the panelWhat it needs
Marked readyThe author takes it out of draft.
Checks passNo failing check, and none still running. A branch with no checks has nothing to wait for.
Approved by a person, or by N peopleThe number of people the repository's merge rules ask for. See Code review.
Migration reviewed by youWhen the diff adds a migration, a person approves it.
No changes requestedThe reviewer approves, or someone with push access uses Dismiss the request.
Threads resolvedShown when the merge rules ask for it. Every thread on a line of code is resolved.
Self-reviewedShown when the merge rules ask for it, or when the author has self-reviewed. The author approved their own pull request, after the last push when stale approvals are dismissed.
Conflicts with mainMerge the base into the branch locally, resolve the files and push.
Up to date with mainShown when the merge rules ask for it. Use Bring in main.

The server enforces the rules, not only the page. A refused merge answers 409 with every unmet rule in one message, for example merge rules not met: needs 2 approvals and has 1; 3 comment threads are unresolved. The rules come from three places:

  • Merge rules: approvals from people (0 to 6), dismissing approvals when new commits arrive, being up to date with the base, and resolving every line thread. An organization sets them for all its repositories, and a repository can raise them. Admins change them in settings, or with /api/orgs/{org}/merge-rules and /api/repos/{owner}/{repo}/merge-rules.
  • Branch rules: requiredChecks names workflows or jobs that must pass on the head before it merges into a matching branch. A failing one reads required check test failed on 3f2a9c1.
  • Protected paths: files whose changes need an approval from named people or teams, for example crates/db/migrations/ needs an approval from team platform.

A caisson's code can also be held until it has been reviewed, when the owner's policy asks for that: caisson/c-z4nwicj7 has not been cleared by review. See Caissons.

Conflicts

When the branch and the base changed the same file, the panel names up to three files under Conflicts with main. Sailfork merges whole files, so resolve conflicts on your machine:

git fetch origin
git merge origin/main
git push

A merge that hits a conflict fails with branch is behind main and conflicts: bring in main first.

Close and reopen

sailfork pr close 12
sailfork pr reopen 12

In the web app these are Close and Reopen. A closed pull request keeps its number and conversation. Reopening is refused while another pull request is open for the same branch and base, and a merged pull request cannot change state. sailfork undo can take back a close or a merge, within 24 hours. See Notifications and activity.

Commands

CommandWhat it does
sailfork pr listList pull requests. Filters: --state open|draft|merged|closed|all (default open), --author <HANDLE|@me>, --head, --base, --file <PATH> (a folder ends in /), --search <TEXT>, --limit (default 30), --all, --cursor.
sailfork pr view [N]Show one.
sailfork pr createOpen one from the current branch.
sailfork pr checkout NCheck out its branch.
sailfork pr diff [N]Show its diff.
sailfork pr edit [N]Change --title, --body, --body-file, add --attach <PATH>, or ask a --reviewer.
sailfork pr ready, sailfork pr draftTake it out of draft, or put it back.
sailfork pr update-branch [N]Merge the base into the branch on the server.
sailfork pr merge [N]Merge it.
sailfork pr close [N], sailfork pr reopen [N]Close it, or reopen it.
sailfork pr checks [N]Show CI checks. --watch polls until none is pending, --fail-fast stops at the first failure, --interval <SECS> (default 5). Exits 0 when all pass, 1 when one failed, 12 while still pending.
sailfork pr review, comment, threads, feedback, threadReview work. See Code review.

Wait and brief

sailfork wait pr blocks until something happens, so a script can sleep until then:

sailfork wait pr 12 --checks
sailfork wait pr 12 --merged --timeout 1h
sailfork wait pr 12 --review

--checks exits 0 when the checks pass and 1 when one fails. --merged exits 1 if the pull request is closed instead. --review returns when a new review or comment arrives and exits 1 if the review asks for changes. Exit 12 means --timeout passed first.

sailfork brief 12 prints everything needed to start on a pull request in one call: the description, the newest comments (--comments <N|all>, default 10), unresolved threads with the code they point at, the diff stat, failed checks with their last log lines, open caissons on the branch and the issues it closes. Add --json for an agent.

Pull requests from agents

An agent's pull request shows the agent's name in monospace, with its client's mark, instead of a person's name. Hover or tap it to see the person whose token it used. A pull request counts as an agent's when the request named an agent client (the CLI and MCP server do) or a caisson opened it. A person's token without that header counts as a person.

Everything else is the same: reviews, checks and the merge rules apply to an agent's pull request as to yours. The merge panel does not count an agent's approval toward the approvals a repository asks for. See Agents.

From a script

Open, list, review, comment and merge over REST: see the API reference. The pulls toolset of the MCP server does the same for an agent.

Who can do what

ActionWho
Read, commentAnyone who can read the repository, unless the conversation is locked.
OpenAnyone who can read the repository and is not blocked by its owner. Someone without write access to a public repository pushes to contrib/<handle>/<name> and opens from there.
Edit, close, reopen, mark readyThe author, and anyone with push access.
Approve, request changes, merge, update the branch, lockAnyone with push access. Your approval of your own pull request is a self-review and never counts toward approvals.

A pull request from outside contributors never starts its workflows on its own. Someone with write access approves the run, and it runs read-only without the repository's secrets.

Limits and common errors

  • A title is at most 256 characters and a comment at most 65,536.
  • Attachments are up to 100 MB each. See Issues.
  • sailfork pr list prints 30 rows unless you pass --limit or --all.
  • Exit 6 is a refused merge or an existing pull request. Exit 10 is a branch that moved under --match-head-commit. Exit 12 is a wait that timed out. sailfork help exit-codes lists all of them.
  • 422 on open: a branch does not exist. Push it first, or leave --no-push off.
  • 409: another open pull request already uses that branch and base, or the merge rules refuse.

Loading Sailfork