# Issues

File, triage, assign and close issues, and filter them by status, label and milestone, from the web app or the CLI.

## File an issue

```sh
sailfork issue create --title "Login loops on Safari" --label bug --priority high
sailfork issue list --status ready --priority high
sailfork issue close 7 --comment "Fixed in the last release."
```

`sailfork issue` works on issues only. Given a pull request's number it fails with `#7 is a pull request, not an issue`.

## Create an issue

### In the web app

Open the repository's **Issues** page and choose **New issue**. The composer asks for a **Title** and a **Description** (Markdown, with a **Preview** tab) and offers these properties: **Status**, **Priority**, **Assignee**, **Labels**, **Milestone**, **Estimate**, **Parent issue** and **Blocked by**. Open **More properties** for the ones not shown. **Attach files** uploads files into the text. Choose **File issue** to save.

While you type the title, the composer lists up to three issues under **Maybe already filed**, open ones first, so you can open one before filing a copy. An issue is listed when its title shares at least two words with yours (short and common words do not count) and more than half of yours. Each links to the issue in a new tab.

### Issue templates

A repository keeps issue templates as Markdown files in `.sailfork/ISSUE_TEMPLATE/`, or in `.github/ISSUE_TEMPLATE/` as GitHub reads them. If the first folder has Markdown files, only it is read. Templates are read from the default branch.

```md
---
name: Bug report
about: Something broke or behaves wrong
title: "Bug: "
labels: [bug]
---

## What happened

## What you expected

## Steps to reproduce
```

| Front matter | What it does |
| --- | --- |
| `name` | The button's name. Default: the file name, with dashes and underscores as spaces. |
| `about` | The line shown when you hover the button. |
| `title` | The starting title. A prefix such as `Bug: ` keeps its trailing space. |
| `labels` | Labels to add. A list, or one comma-separated string. |

The text after the front matter is the starting description. GitHub's YAML issue forms are not read.

When a repository has templates and the composer is empty, **Start from** lists them. Choosing one fills in the title and description and adds its labels to the ones already chosen. Once you have typed anything, the list goes away, so a template never overwrites a draft.

To make one from the composer, write a title or description, choose **Save as template** and give it a name and an optional "When to use it". It commits `<name>.md` to the default branch, or to a new branch with a link to open a pull request when the branch's rules keep a direct commit out. People with push access see this button. Pull requests have no template.

### From the CLI

| Flag of `sailfork issue create` | What it does |
| --- | --- |
| `-t, --title <TITLE>` | Required. |
| `-b, --body <TEXT>`, `--body-file <FILE>` | The description. `--body-file -` reads stdin. |
| `-l, --label <LABEL>` | Add a label. Repeat for several. |
| `--priority <urgent\|high\|medium\|low\|none>` | The priority. |
| `--estimate <1\|2\|3\|5\|8>` | Size in points. |
| `--due <YYYY-MM-DD>` | Due date. |
| `--milestone <NAME>` | Milestone name. |
| `--parent <N>` | Make it a sub-issue of issue N. |
| `--blocked-by <N>` | An issue that must finish first. Repeat for several. |
| `--assignee <HANDLE>` | The one person who answers for it. |
| `--stage <reported\|triaged\|fixing\|review>` | The starting stage. |
| `--attach <PATH>` | Upload a file and link it in the text. Repeat for several. |
| `--idempotency-key <KEY>` | Retrying with the same key returns the issue already created. |

## The issue page

The page has the title and description, a **Properties** panel, **Sub-issues**, the **Activity** timeline of comments and changes, and a **Following** control. A repository's pull requests that close the issue show as a card on it. Use **Edit title and description** to change the text, and the comment box ("Leave a comment, @ to mention") to talk. Reactions are on the issue and on each comment.

The title, description and state can be changed by the issue's author. Everything else (status, assignee, labels, priority and the rest) needs push access. Locking the issue leaves only people with write access able to comment.

`sailfork issue view 7` prints the issue with its relations, comments and timeline.

## Statuses

An issue has one status, derived from its stage, whether it is open and why it closed:

| Status | Stage | Meaning |
| --- | --- | --- |
| Triage | Reported | Waiting for someone to triage it. |
| Ready | Triaged | Ready to be picked up. |
| In progress | Fixing | Someone is working on it. Reads as Ready once an agent's lease on it lapses. |
| In review | Review | A pull request says it fixes this. |
| Done | closed | Closed as done. |
| Canceled | closed | Closed as won't do. |
| Duplicate | closed | Closed as a duplicate of another issue. |

Set the status from the **Status** property, or with `sailfork issue edit 7 --status ready`. The CLI takes `triage`, `ready`, `in-progress`, `in-review`, `done`, `canceled` and `duplicate`, and sets stage and state together. `--stage` moves only the stage.

Closing ends an issue wherever it stood:

```sh
sailfork issue close 7
sailfork issue close 7 --reason wont-do --comment "Out of scope for this quarter."
sailfork issue close 7 --duplicate-of 3
sailfork issue reopen 7
```

`--reason` is `done` (the default), `wont-do` or `duplicate`. `--duplicate-of` implies `duplicate`. In the web app, closing as a duplicate asks which issue it duplicates.

### Close it from a pull request

A pull request that says `closes #7`, `fixes #7` or `resolves #7`, or that was opened with `sailfork pr create --issue 7`, or from a branch named `issue/7-...`, links the issue. Linking moves the issue to In review. Merging the pull request closes it. See [Pull requests](https://status.sailfork.com/docs/pull-requests#link-issues).

## Assignees

An issue has at most one assignee, the one person who answers for it. Set it from **Assignee**, or:

```sh
sailfork issue edit 7 --assignee ada
sailfork issue edit 7 --no-assignee
```

In the web app, **Claim this issue** assigns it to you and moves it to In progress.

An agent takes an issue with a lease, which never changes the assignee. `sailfork issue edit 7 --assign-agent <TOKEN>` asks one of your agent tokens to take it, `--no-agent` withdraws the request, and a request not started within 30 minutes expires. `sailfork issue claim`, `next`, `start` and `ship` are the agent side. See [Agents](https://status.sailfork.com/docs/agents).

## Labels and milestones

An issue carries at most 20 labels, each up to 50 characters, unique ignoring case. A milestone name is at most 80 characters. Issues name labels and milestones by text, so a name with no record still works. A record adds a description, and for a milestone a due date and an open or closed state.

In the web app, the **Labels** and **Milestones** pages of the repository list them, most used first, with the number of open and closed issues. They have **New label**, **New milestone**, rename, describe and delete. Renaming a label changes it on every issue that has it. Deleting a label or milestone removes it from every issue that carries it. Anyone with push access can change them.

```sh
sailfork label list
sailfork label create bug --description "Something is broken"
sailfork label edit bug --name-to defect
sailfork label delete defect --yes
sailfork milestone create "v1.0" --due 2026-12-01
sailfork milestone edit "v1.0" --title-to "1.0" --no-due
sailfork milestone close "1.0"
sailfork milestone reopen "1.0"
sailfork milestone delete "1.0" --yes
```

On an issue, `--label` replaces the labels, `--add-label` and `--remove-label` change one, and `--clear-labels` empties them. `--milestone <NAME>` moves it and `--no-milestone` takes it out. Closing a milestone leaves its issues as they are. `--dry-run` on a delete says what would go.

## Views and filters

The issues list opens on **All** and keeps its query in the address, so a view can be saved and shared. The view tabs are **My issues**, **Active** (In progress and In review), **Ready**, **Triage** and **All**. A list across all of an owner's repositories adds **Needs input**, for issues where an agent left a question for a person.

- **Filter** by assignee, agent, priority, label and milestone. **Clear all** removes them.
- **Find an issue** matches the title and description, or a number such as `#12`.
- **Display options**: **Layout** (list or board), **Group by** Status or Assignee, **Order by** Priority, Newest or Recently updated, and **Show closed issues**.
- In Triage, you can snooze an issue for a week or until tomorrow. Snoozed issues stay out of the Triage view.

From the CLI:

```sh
sailfork issue list
sailfork issue list --status ready --priority high
sailfork issue list --assignee none --label bug --json=number,title,status
sailfork issue list --author @me --mentions ada
sailfork issue list --query "login loop" --all
```

| Flag of `sailfork issue list` | What it does |
| --- | --- |
| `--state <open\|closed\|all>` | Default `open`. |
| `--status <STATUS>`, `--stage <STAGE>` | Filter by status or stage. |
| `--label`, `--milestone`, `--priority`, `--parent <N>` | Filter by that field. |
| `--assignee <HANDLE\|none>` | A handle, or `none` for unassigned issues. |
| `--author <HANDLE\|@me>`, `--mentions <HANDLE\|@me>` | Who opened it, or whose `@mention` is in its title or description. |
| `-q, --query <TEXT>` | Search titles and bodies. |
| `--sort <newest\|oldest\|priority\|updated>` | Order of the rows. |
| `--limit <N>` (default 30), `--all`, `--cursor <CURSOR>` | Paging. |

To search across a repository's issues with qualifiers, see [Search](https://status.sailfork.com/docs/search).

## Work graph

The graph draws one issue or pull request and what connects to it. Open it with **Graph** on an issue page, shown when the issue has a parent, sub-issues, blockers or issues it blocks, or with **View graph** in the **Stack** section of a pull request in a [stack](https://status.sailfork.com/docs/pull-requests#stacked-pull-requests). The address is `/<owner>/<repo>/graph?focus=issue-7` or `focus=pull-12`. Without a valid `focus` the page says "No item to graph".

For an issue, the graph shows its parents up the chain, its sub-issues, the issues it waits on and the issues that wait on it, and the pull requests that close any of them, with the pull requests they are stacked on. For a pull request, it shows the whole stack and the issues those pull requests close. An item with nothing connected reads "stands alone".

| Line | Meaning |
| --- | --- |
| Solid | Parent to sub-issue |
| Dashed, with an arrow | Blocker to the issue it blocks |
| Dotted, with a dot | An issue to its pull request, and a pull request to the one stacked on it |

Each node shows the number, title, status, a checks mark on an open pull request, and **Ready now** on an issue that is Ready with no open blocker and no open sub-issue. A summary line counts issues, pull requests and the ready ones. Choose a node to open it, or the crosshair on it to focus the graph there, which changes `focus`. A busy graph stops at 150 nodes and each node admits at most 8 neighbors on its own. A **+N more** node opens the rest, and the summary says how many are not shown. Zoom with the buttons.

## Attachments

Drop or paste files into a description or comment, or choose **Attach files**. From the CLI, `--attach <PATH>` on `issue create`, `issue comment` and `pr comment` uploads a file and links it, and `sailfork attachment` handles files by hand:

```sh
sailfork attachment upload after.png report.pdf -R fenil/ocean-landing
sailfork attachment download <link-from-a-comment> -o after.png
```

`upload` prints a Markdown link for each file: `![name](url)` for images and videos so they show inline, `[name](url)` for anything else. A file is up to 100 MB. Only png, jpeg, gif, webp, avif, mp4, webm, quicktime and pdf show inline, and every other type downloads. On a public repository anyone can fetch an attachment.

## Mentions

Write `@ada` in a description or comment, outside a code block, to notify that person and make them follow the issue. They need read access to the repository. `@acme/design` mentions the members of that team of the organization, at most 50 people for one change. The editor suggests people and teams as you type. Who follows an issue is described under [Notifications and activity](https://status.sailfork.com/docs/notifications).

`sailfork issue subscribe 7` and `sailfork issue unsubscribe 7` follow and unfollow from the terminal.

## Commands

| Command | What it does |
| --- | --- |
| `sailfork issue list`, `view`, `create` | Find, read and file issues. |
| `sailfork issue edit N` | Change any field: `--title`, `--body`, `--status`, `--stage`, `--assignee`, `--priority`, `--estimate` (or `--no-estimate`), `--due` (or `--no-due`), `--parent` (or `--no-parent`), `--blocked-by` (or `--clear-blockers`), and the label and milestone flags above. |
| `sailfork issue comment N` | Comment with `--body`, `--body-file` or `--attach`. `--update` posts it as a progress update. |
| `sailfork issue close N`, `reopen N` | Close and reopen. |
| `sailfork issue react N <REACTION>` | React with `+1`, `-1`, `laugh`, `hooray`, `confused`, `heart`, `rocket` or `eyes`. `--comment <ID>` reacts to a comment, `--remove` takes it back. |
| `sailfork issue subscribe N`, `unsubscribe N` | Follow or stop following. |
| `sailfork issue claim`, `release`, `context`, `next`, `start`, `ship` | The agent workflow. See [Agents](https://status.sailfork.com/docs/agents). |
| `sailfork label ...`, `sailfork milestone ...` | Manage labels and milestones. |

`sailfork brief 7` prints what you need to start on an issue in one call: the description, the newest comments (`--comments <N|all>`, default 10), its lease, parent, blockers, sub-issues and the pull requests that close it, plus repository notes. Add `--json` for an agent.

## From a script

Create, list, update, comment on and claim issues over REST, with `Idempotency-Key` on writes: see [the API reference](https://status.sailfork.com/docs/api). The `issues` toolset of the [MCP server](https://status.sailfork.com/docs/mcp) does the same for an agent.

## Limits and common errors

- A parent and its sub-issues are in the same repository, nested at most 32 deep. Blockers are in the same repository.
- Issue lists return 1 to 100 rows a page, 30 by default.
- Every issue write accepts an `Idempotency-Key` of 1 to 200 characters. A retry with the same key and body returns the first response, and the same key with a different request is 409. Keys last a day.
- `403`: the issue is locked and you lack write access, the owner of the repository blocked you, or the issue came over from GitHub into a pull mirror, where issues are read-only.
- `409` on claim: another token holds the lease, the issue is closed or blocked, or it is an epic.
- `sailfork undo` takes back a comment, a label or status change, a close and a few other actions within 24 hours. See [Notifications and activity](https://status.sailfork.com/docs/notifications#take-back-an-action).

---

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