# 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.

```sh
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

```sh
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
```

| Flag | What it does |
| --- | --- |
| `-t, --title`, `-b, --body`, `--body-file <FILE>` | Set the title and description. `--body-file -` reads stdin. |
| `--fill` | Take 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. |
| `--draft` | Open it as a draft. |
| `--reviewer <HANDLE>` | Ask one person to review it. |
| `--issue <N>`, `--closes <N>` | Link an issue (repeatable). See [Link issues](#link-issues). |
| `--no-push` | Do 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](https://status.sailfork.com/docs/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.

```sh
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:

```sh
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.

```sh
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.

| What | Behavior |
| --- | --- |
| Page | A pull request in a stack shows a **Stack** section with the tree and a **View graph** link to the [work graph](https://status.sailfork.com/docs/issues#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`. |
| Review | Each pull request is reviewed, checked and held by the merge rules on its own. |
| Merge from the page | On 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}`. |
| Merge | `sailfork 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. |
| Waiting | A 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 merge | The 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 queue | When the base takes merges through the [merge queue](https://status.sailfork.com/docs/api-repositories#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](https://status.sailfork.com/docs/mcp), and `pr create` and `pr edit` take `onto` there too.

## Link issues

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](https://status.sailfork.com/docs/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:

| Method | Result |
| --- | --- |
| Merge | The base fast-forwards to the branch, or gets one merge commit when it has moved on. |
| Squash | The commits become one commit on the base, named after the pull request. |
| Rebase | Each 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.

```sh
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
```

| Flag | What 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-run` | Check that it can merge and change nothing. |
| `--auto` | Merge 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-branch` | Keep 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](https://status.sailfork.com/docs/branches#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 panel | What it needs |
| --- | --- |
| Marked ready | The author takes it out of draft. |
| Checks pass | No failing check, and none still running. A branch with no checks has nothing to wait for. |
| Approved by a person, or by N people | The number of people the repository's merge rules ask for. See [Code review](https://status.sailfork.com/docs/code-review). |
| Migration reviewed by you | When the diff adds a migration, a person approves it. |
| No changes requested | The reviewer approves, or someone with push access uses **Dismiss the request**. |
| Threads resolved | Shown when the merge rules ask for it. Every thread on a line of code is resolved. |
| Self-reviewed | Shown 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 main | Merge the base into the branch locally, resolve the files and push. |
| Up to date with main | Shown 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](https://status.sailfork.com/docs/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:

```sh
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

```sh
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](https://status.sailfork.com/docs/notifications#take-back-an-action).

## Commands

| Command | What it does |
| --- | --- |
| `sailfork pr list` | List 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 create` | Open one from the current branch. |
| `sailfork pr checkout N` | Check 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 draft` | Take 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`, `thread` | Review work. See [Code review](https://status.sailfork.com/docs/code-review). |

### Wait and brief

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

```sh
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](https://status.sailfork.com/docs/agents).

## From a script

Open, list, review, comment and merge over REST: see [the API reference](https://status.sailfork.com/docs/api). The `pulls` toolset of the [MCP server](https://status.sailfork.com/docs/mcp) does the same for an agent.

## Who can do what

| Action | Who |
| --- | --- |
| Read, comment | Anyone who can read the repository, unless the conversation is locked. |
| Open | Anyone 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 ready | The author, and anyone with push access. |
| Approve, request changes, merge, update the branch, lock | Anyone 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](https://status.sailfork.com/docs/issues#attachments).
- `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.

---

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