Issue trackers
Connect an issue tracker shows how to connect Linear, Jira, and GitHub Issues and bind them to Projects.
Closing references
A pull request that the publish node opens refers to its issue as follows:
| Tracker | The pull request carries | What closes the issue |
|---|---|---|
| GitHub | Closes owner/repo#12 in its description | GitHub closes the issue when the pull request merges into the repository's default branch. |
| Jira | The issue key at the start of its title | Jira links the pull request through its GitHub integration. Moving the issue on merge needs a Jira automation rule. |
| Linear | Closes ENG-12 in its description | Linear's GitHub integration completes the issue when the pull request merges. |
devboxes closes no issue itself. The tracker closes it from the Closes reference in the pull request, as Take an issue from Chat describes. When the tracker leaves the issue open after a person merges the pull request, the issue keeps devboxes: ready to merge until someone closes it.
Status labels on GitHub
On GitHub, an issue that a Session works on shows the status of that work as a label. devboxes updates the label within about a minute of a change. GitHub creates a status label the first time devboxes adds it to an issue:
| Status | GitHub label | Meaning |
|---|---|---|
| queued | devboxes: queued | The work waits to start. |
| running | devboxes: running | The agent works on the issue. |
| reviewing | devboxes: reviewing | devboxes reviews the pull request, fixes its findings, or checks the fix, or the work waits for its automatic Review to start. |
| ready to merge | devboxes: ready to merge | The Review passed. A person merges the pull request, or devboxes merges it when the Project merges after Review. |
| blocked | devboxes: blocked | devboxes stopped and a person must act: the work failed, the Review stopped and left the work to a person, or the automatic Review could not start. |
| paused | devboxes: paused | The work paused because its model account's usage limit or credit is exhausted. A person continues it once the limit resets or the credit is renewed, or now on another account. |
Cancelled work, work whose Blueprint has no Review, and a pull request that merged at its reviewed commit while its Project waited to merge it after Review leave no label. A question from the agent does not change the label, because the work keeps running while devboxes asks in Chat.
An issue carries at most one of these labels. When several Sessions worked on the issue, the label follows the most recent one.
devboxes writes a status label only while the issue is open and marked for devboxes: labelled devboxes on GitHub. When someone removes the devboxes label, devboxes stops updating the issue and removes its status label at the next change of the work's status. Closing the issue removes the status label, and reopening it brings the label back within about a minute.
Linear agent sessions
In Linear, the agent session that the delegation or mention opened shows the status instead of a label. Linear sets the session's state from devboxes' latest reply in it, and devboxes picks the kind of reply from the status of the session's work:
| The session's work, and devboxes' turn | devboxes' reply | Session state |
|---|---|---|
| The running work asked a question that nobody has answered yet | elicitation | awaiting input |
| Any of the work is queued, running, or reviewing | thought | active |
| Nothing is queued, running, or reviewing, and the work is blocked, the turn failed, or devboxes refused it | error | error |
| Nothing is queued, running, or reviewing, nothing above applies, and the work is paused | elicitation | awaiting input |
| Anything else, or no work | response | complete |
A reply after you stop the session is the exception: it is a response, or an error when devboxes could not cancel the work. A request that fails with ISSUE_STOPPING is an error too, also in the session that stopped the work. Answer a question with a reply in the session, and devboxes passes your answer to the work.
The session links every pull request of its work. The agent session's plan lists the stages of the work in its devboxes Sessions: the work itself, and once a Session's automatic Review starts or could not start, the Review and the merge. A stage is pending, in progress, completed, or canceled. Failed or cancelled work cancels the work stage. Paused work keeps it in progress, because a person can continue it, and devboxes asks how to continue it with an elicitation. A Review that stopped and left the work to a person, or could not start, cancels the Review and the merge. After a passed Review, the merge is pending while a person decides whether to merge, in progress while devboxes waits to merge the pull request, and completed once the pull request merged at the reviewed commit. The plan changes only when devboxes replies in the session, so it can show an earlier stage until the next reply. Linear offers plans as a preview: when Linear rejects a plan, devboxes still replies.
When devboxes starts work for an issue that is delegated to it, devboxes moves the issue to the first workflow state of type started in its Team. It leaves every issue in triage where it is, because Linear asks to keep an issue that an automation delegated in triage and devboxes cannot tell an automation's delegation from a person's. It also leaves an issue that is already started, completed, or canceled. An issue on which someone only mentioned devboxes keeps its state.
When you stop the session in Linear, devboxes cancels the session's running work with your permissions in this thread, without asking the model, and replies with what it stopped. The Chat policy must allow sessions.cancel. Linear then shows the session as complete, or as an error when devboxes refused to cancel.
Jira issues show no devboxes status.
Blocked issues
devboxes uses the blocked-by relations of your tracker and keeps no dependency list of its own. When an issue is marked for devboxes, devboxes reads it and checks its blocked-by issues. While any of them is open, devboxes starts nothing, names the open blockers, and says that it will check again when it hears about them in this conversation.
Some tracker events give devboxes a new turn in the conversations of the issues marked for devboxes that the event unblocks. In that turn, devboxes checks the blocked-by issues again and starts the work when none is open:
| Tracker | Events that give a blocked issue a new turn | Not covered |
|---|---|---|
| GitHub | Closing an issue, also by merging a pull request that closes it, for the blocked issues in the same repository. Removing a "blocked by" relation, for the issue it blocked. | Blocked issues in another repository. |
| Jira | Moving an issue to a status in the Done category, for the issues it "blocks". Deleting a "blocks" link, for the issue it blocked. | None. |
| Linear | None. devboxes checks blocked issues only at handoff. | Every blocker. |
When no event covers a blocker, comment on the blocked issue, or mention @devboxes in Linear, once the blocker is done. A redelivered event gives no second turn, and an issue whose conversation has ended gets no turn.
Who can read the issue
The issue is the specification of its work. devboxes does not copy the issue's description into the agent's instruction, nor, on GitHub and Jira, into devboxes' conversation. devboxes and the agent read the issue with issues.read, which returns its comments too. Two readers can always get their own issue, even when the Chat policy or the Blueprint leaves issues.read out:
- devboxes in an issue's conversation in the tracker reads that issue.
- The agent of a Session that works on an issue reads that issue. When the Blueprint binds no
issues.readcapability, the agent gets alinked-issuecapability, which takes no arguments and reads that issue.
Without issues.read, devboxes can get only its conversation's issue, with action get. devboxes refuses any other read with ISSUE_NOT_AUTHORIZED. It looks up the issue that devboxes names before it compares, so a tracker error can come before ISSUE_NOT_AUTHORIZED.
When the Chat policy allows issues.read, anyone who can post in a channel that a Chat Channel routes to a Project, including people outside your Organization, can have devboxes read the issues of that Project's tracker, with their comments. Connect only channels whose members you trust with those issues.
issues.read and issues.write
issues.read with action list lists the open issues of the bound scope. Its state lists the closed issues or all of them instead. A closed issue is closed on GitHub, in the Done status category on Jira, and in a completed or canceled state on Linear. A query searches those issues with the tracker's own search: GitHub issue search, Linear's searchIssues, and a Jira text ~ JQL query.
A listed issue carries its tracker's own priority, assignee, and date fields:
| Tracker | Priority and assignee | State and dates |
|---|---|---|
| Linear | priority, priorityLabel, assignee | state.type, createdAt, updatedAt, completedAt, canceledAt |
| Jira | fields.priority, fields.assignee | fields.status, fields.created, fields.updated, fields.resolutiondate |
| GitHub | assignees | state, created_at, updated_at, closed_at |
An issue that issues.read gets on Linear carries the same state type and dates. GitHub issues carry an Organization's issue fields, such as a priority field, in issue_field_values.
An issue that issues.read gets carries its blocked-by data: inverseRelations on Linear, fields.issuelinks on Jira, and blocked_by on GitHub, which lists the blocking issues' number, title, state, and html_url.
On GitHub, issueId is the issue number. A pull request number, or the number of an issue that moved to another repository, fails with TRACKER_RESOURCE_NOT_FOUND. transition takes a stateId of open, completed, not_planned, or duplicate. When GitHub rate-limits a request, the operation fails at once with TRACKER_RATE_LIMITED and names the time after which GitHub accepts requests again. devboxes sends a create or a comment only once, so after an uncertain failure, read the issues before you try again.