Connect GitHub Issues

Owners and admins connect GitHub Issues. Turn on Chat first, because issue conversations use the same policy and Persona.

devboxes works with GitHub issues through the devboxes GitHub App installation that connects your repositories. It acts on issues as the App's bot account, with a token for the bound repository only, and stores no GitHub token.

1. Connect GitHub if you have not, and give the App access to the repository.

2. Find the installation ID in the githubInstallationId field of repositories.connections.

3. Connect the installation and bind a Project with this prompt for your coding agent:

   Prompt for your coding agentCopy prompt

   To do it yourself, connect the installation:

   { "organizationId": "<organization id>", "installationId": "<installation id>" }

   devboxes invoke chat.connect-github --input @github-issues.json

   Then bind a Project to a repository by its owner/repo name:

   {
     "organizationId": "<organization id>",
     "projectId": "<project id>",
     "configuration": { "kind": "github", "scopeId": "acme/web" }
   }

   devboxes invoke issues.configure --input @github-repository.json

   The result's scopeId is the repository's GitHub ID, so the binding survives a rename. Binding creates the devboxes label in the repository if it is missing. Several Projects can share one repository.

To have devboxes work on an issue, add the devboxes label. The label counts only when a person with triage access or higher, or another App's bot, applies it. An issue template that applies the label for its author starts nothing until such a person removes the label and adds it again. devboxes reads the issue and its earlier comments, then replies with comments from the App's bot account. Comments from people with triage access or higher, and from other bots, continue the conversation; other comments start nothing. The agent is told to put Closes with the issue in its commit message, as Take an issue from Chat describes.

Removing the label, transferring the issue, or deleting it ends the conversation. Adding the label again starts a new one.

GitHub does not retry a webhook delivery that fails. Every five minutes, devboxes asks GitHub to redeliver the issue, comment, and issue dependency events that GitHub first sent in the last two hours and that no attempt delivered. devboxes stops asking once an event has three attempts. The devboxes API servers ask independently, so with several servers an event can get two attempts plus one per server. A label added while devboxes was unavailable starts work when GitHub redelivers it, and a redelivered event never starts work twice.