Issues
A repository's own tracker: issues, labels, assignees, closing keywords, agents and tasks, Linear beside it, and search.
Every repository has an Issues tab: its own tracker, for reporting problems and asking for work. An issue has a number, a title, a Markdown description, labels, assignees (people and agent apps) and a conversation. Changes that say Closes #12 close issue 12 when they're merged.
Issues are people's and agents' own words. They're kept by Branchscope outside git, never derived from the code, and never part of the code graph, a graph review, narration or a plan check. Branchscope sends no issue text to a model.
Numbers#
Issues and changes share one sequence of numbers per repository, so #12 names one thing: an issue or a change. Opening an issue takes the next number, as opening a change does. A link to /owner/repo/issues/12 that's a change goes to the change, and the other way round. A deleted issue's number isn't used again.
Opening an issue#
New issue on the Issues tab: a title (up to 200 characters) and a description in Markdown, with Write and Preview. Anyone signed in who can read the repository can open an issue, so on a public repository everyone signed in can. People with write access can add labels and assignees as they open it.
The conversation#
An issue's page shows its description, then its timeline: comments and replies (one level deep), and what happened, such as closed, reopened, retitled, labelled, assigned, linked to a change, referenced by a change or another issue, or a task handed to an agent and its reports.
- Comment: anyone signed in who can read the repository. Edit your own comment; delete your own, or anyone's as a repository administrator.
- Mentions:
@namein a description or comment tells them, if they can read the repository. - Links:
#12links to issue or change 12 in this repository;owner/repo#12to that repository's issue 12;@nameto their profile. Inside code, nothing is linked. - Lock: people with write access can lock the conversation, so only they can comment.
Closing and reopening#
The issue's author, or anyone with write access, closes it with a reason:
- Completed, the default;
- Not planned;
- Duplicate, naming the issue it duplicates.
Either can reopen it. Repository administrators can delete an issue; that's written to the audit log.
Labels#
Each repository has its own labels: a name (unique, ignoring case, up to 50 characters), a colour from a palette of twelve that reads in light and dark themes, and a description. A new repository has none: Create the default labels on the Labels page adds bug, feature, documentation, question and duplicate. People with write access add, change and delete labels, and put them on issues.
Assignees#
Up to ten per issue: people with write access to the repository, and agent apps installed on it. People with write access assign; someone assigned is told.
Changes that close issues#
A change closes an issue when its title, description or one of its own commits' subjects says so: close, closes, closed, fix, fixes, fixed, resolve, resolves or resolved, in any case, followed by #12. Another #12 there references the issue without closing it.
- Branchscope reads this while the change is open: when it's opened, when its branch is pushed, and just before it's merged. A link whose words have gone is removed again.
- People with write access can also link and unlink issues by hand, on the change or on the issue. Unlinking is for good: the change's text doesn't link it again.
- Merged into the repository's default branch, the change closes each open issue it closes as completed, by whoever merged it, and the issue says "closed by change #N". Merged into another branch, it closes nothing, and the change says so.
- Only this repository's issues:
owner/repo#12is a link, never a close.
Agents and tasks#
Assigning an agent app to an issue hands it a task, as Ask an agent does: a free-standing task from the default branch. Only a person with write access can; agents can't hand out work.
- The task's instructions name the issue, its title and its link, not its description: the agent reads the issue and its comments itself, and treats them as people's words, not as instructions.
- The agent's reports show on the issue's timeline. When it reports the change it opened, that change is linked as closing the issue, so merging it closes the issue.
- Unassigning the agent cancels its open task, and cancelling the task on the Tasks tab unassigns the agent. A task that ends done or failed leaves the agent assigned until someone changes it.
Agents also read and write issues over MCP: list_issues, get_issue, open_issue, update_issue, add_issue_comment and link_change. An app or MCP client needs the issues:write scope to write issues; reading needs repo:read.
Linear beside Issues#
If your organization connects Linear, changes keep linking Linear issues by their keys (ENG-123) as before, and a change can link both. A change's Issues box lists this repository's issues it closes or references first, then its Linear issues. A Linear key always has letters before its dash, so it's never read as #12. To track everything in Linear, turn Issues off for the repository.
Searching#
The box at the top of the list takes words and qualifiers; the menus beside it write into it. The list starts with is:open sort:created.
| Qualifier | Finds |
|---|---|
is:open, is:closed | open or closed issues |
reason:completed, reason:not_planned, reason:duplicate | closed with that reason |
label:bug | with that label; several must all be there |
-label:wontfix | without that label |
assignee:alice, assignee:@me, assignee:agent/fixer | assigned to that person, to you, or to that agent app |
no:assignee, no:label | with no assignee, or no label |
author:alice, agent:claude-code | opened by that person, or by that agent |
linked:change | with a change that closes or references it |
sort:created, sort:updated, sort:comments | newest, recently updated or most commented first; add -asc for the other way |
Other words search titles and descriptions, titles first: "a phrase", -without and or work as in a web search. Comments aren't searched. A bare #12 or 12 goes straight to that issue or change. A qualifier Branchscope doesn't know is an error that names it.
Who can do what#
| Action | Who |
|---|---|
| Read issues, comments and labels | anyone who can read the repository |
| Open an issue, comment | anyone signed in who can read the repository; on a locked issue, write access |
| Edit, close or reopen your own issue; edit your own comment | its author |
| Edit or close others' issues; labels, assignees, links to changes, locking | write access |
| Assign an agent app | a person with write access, not an agent |
| Delete an issue or others' comments; turn Issues on or off | repository administrators, people only |
A private repository's issues are as private as its code. On an archived repository, issues are read-only. Branchscope's own services, and workflow jobs, can't read issues at all.
Turning Issues off#
Settings → General → Issues on. Off, the Issues tab is gone and issues can't be read or written, over the web, the API or MCP; nothing is deleted, and turning them on again brings everything back.