Start tasks from issues

Connect Linear, Jira, or GitHub Issues, and bind a Project to a Linear Team, a Jira Project, or a GitHub repository. Then people start tasks from issues:

• In Linear, delegate an issue to devboxes or mention @devboxes on the issue.
• In Jira, assign an issue to the devboxes account.
• In GitHub, add the devboxes label to an issue.
• In Chat, ask devboxes to take the issue, as Take an issue from Chat describes.

Later comments on the issue continue the conversation of a handoff in the tracker.

Owners connect Linear and Jira, because these connections store a credential. GitHub Issues stores none, so owners and admins connect it. Turn on Chat first, because issue conversations use the same policy and Persona.

issues.configure and issues.configuration return a handoff field. For Linear and Jira, { "kind": "assignee", "accountId": "<account id>" } names the account that issues are delegated or assigned to. For GitHub, { "kind": "label", "name": "devboxes" } names the label.

An owner or admin can also ask devboxes in Chat to bind a Project to a tracker, when the Chat policy allows issues.configure and they linked their chat account. devboxes refuses anyone else. Its reply includes the handoff, so people learn how to start a task from an issue.

Take an issue from Chat

People who work only in Chat can give devboxes an issue there, for example "take api#12", "work on #12", a link to the issue, or "take the waitlist crash bug". devboxes looks for the issue in the tracker bound to the Project:

• devboxes takes an issue reference or a link directly.
• For a description, devboxes searches the Project's open issues with issues.read, action list, and a query. When exactly one issue matches, devboxes takes it and names it in its reply. When several match or none does, devboxes lists the candidates with their number, title, and state, and takes nothing until you say which one.

Taking an issue starts a Session with sessions.dispatch and its issue field, which takes the issue as issues.read takes issueId. You can take an issue with the CLI too:

{
  "organizationId": "<organization id>",
  "projectId": "<project id>",
  "title": "Fix the waitlist crash",
  "instruction": "Fix the crash described in the issue.",
  "inputs": {},
  "issue": "12"
}

devboxes invoke sessions.dispatch --input @take.json

devboxes then does three things:

1. It links the issue to the Session. sessions.list and sessions.inspect show the issue as trackerIssueUrl. A Session that devboxes starts from a label, assignment, or delegation in the tracker gets the same link.
2. It marks the issue as devboxes' own, in the same way a person starts a task from an issue: the devboxes label on GitHub, and the devboxes account as assignee on Jira. devboxes does not delegate Linear issues to its own app yet, so a Linear issue stays as it is. The result's issue.marked says whether the mark was set. When the tracker refuses it, the work still runs, and issue.markError says why.
3. When the work's Blueprint has a publish node, it tells the agent how its latest commit message refers to the issue. A pull request that the publish node opens takes that message's first line as its title and the rest as its description. Closing references lists what the pull request carries in Linear, Jira, and GitHub, and what closes the issue.

Taking an issue needs the Chat policy to allow issues.write, because it writes to the tracker. Without it, the request fails with DELEGATION_CAPABILITY_FORBIDDEN. While a Session works on the issue, with a queued or running Run or an active review, taking the issue again fails with ISSUE_IN_PROGRESS and names that Session, and devboxes starts nothing new. When you asked for more than the issue, devboxes keeps that request as waiting work for that Session in chat channels, and starts it when the Session's work finishes. Where waiting work is unavailable, such as in a tracker, devboxes says that the work is still running and that you can ask again once it finishes.

Work that devboxes starts in a conversation in the tracker links that conversation's issue without taking it, so it needs no issues.write. While a Session that this conversation did not start still works on that issue, for example one taken from Chat or one that another agent session started in Linear, devboxes starts no second Session. The start fails with ISSUE_IN_PROGRESS_ELSEWHERE, devboxes answers with an error that the issue is already being worked on elsewhere, and the work stays with the thread that holds it.

After someone stops the work on an issue, its Session takes a short while to stop. Until it has stopped, devboxes starts no new work on the issue, from any conversation, including a new delegation of the issue in Linear. The start fails with ISSUE_STOPPING, and devboxes answers with an error that the earlier work is still stopping. Ask again once it has stopped.

Follow the work on the issue

On GitHub, the issue shows the status of its work as a label. In Linear, the agent session that the delegation or mention opened shows it. Status labels and Linear agent sessions list what the statuses mean. Jira issues show no devboxes status.

Blocked issues

devboxes starts nothing on an issue while one of its blocked-by issues is open. Blocked issues lists the tracker events that let devboxes check again.

Let agents work with issues

A Blueprint with the issues.read and issues.write capabilities lets its agent read, create, update, and comment on issues in the bound Team, Project, or repository. See Write a Blueprint. You can call issues.read and issues.write yourself too. issues.read and issues.write lists what they accept in Linear, Jira, and GitHub.

Disconnect

issues.disconnect unbinds a Project. chat.disconnect removes the Linear, Jira, or GitHub Issues connection. Disconnecting the GitHub installation with repositories.disconnect, or uninstalling the devboxes GitHub App from GitHub, also removes its GitHub Issues connection.