GitHub Issues as a Durable Queue for Coding Agents

Updated 8 November 2026 · Standard formula, shown below

GitHub Issues can serve as a durable, reviewable queue for unattended coding agents: each issue records a task, while labels and assignment communicate whether it is ready, active, or blocked. This setup works best when an agent runs from a controlled automation workflow, claims one issue at a time, and reports its changes through a pull request rather than merging its own work.

What You’ll Need

A GitHub repository where you can create issues, labels, and automation workflows.
An agent runner that can check out the repository and open pull requests. Configure its GitHub credentials with only the permissions it needs; avoid placing long-lived secrets in issue text or committed files.
A workflow trigger, such as a scheduled run or an approved repository event, plus a way to prevent overlapping workers.
A clear task format, an issue template, and a human reviewer responsible for checking proposed changes.

Step-by-Step

Define the queue states. Create a small set of labels, for example agent:ready, agent:working, agent:blocked, and agent:review. Decide what each means and document it in the repository. Treat the labels as workflow state, not as a substitute for issue history. Use one authoritative state label at a time, or make your automation reliably remove the old state when it adds a new one.
Write an issue template for actionable work. Include a concise goal, relevant context, acceptance criteria, likely files or subsystems, and explicit constraints. Ask submitters to provide steps to reproduce bugs and expected behavior when relevant. Separate requirements from suggestions, and state what the agent should do if information is missing. Do not include credentials, private data, or instructions that override repository security controls.
Choose a safe eligibility rule. Have the runner select only open issues carrying agent:ready from the intended repository. Consider requiring an additional label, such as agent:approved, if tasks need human triage first. Exclude issues marked blocked, duplicate, or otherwise ineligible. Keep the query and selection logic in the workflow configuration so the rule is visible and reviewable.
Prevent two workers from claiming the same issue. Use a workflow-level concurrency lock or another atomic claim mechanism. Before starting, re-check that the issue is still open and ready; then change its state to working and record the run identifier or start time in a comment. A label update alone is not a perfect lock: two workers can read the ready state at nearly the same time. Concurrency controls should cover the whole claim-and-run operation, or the runner must handle a failed claim and exit without editing.
Run the agent with a narrow task boundary. Fetch the issue body and relevant discussion as input, but treat all issue content as untrusted data. The agent should work in a fresh branch or isolated checkout, follow repository instructions, run the stated checks, and avoid changing unrelated files. Do not let issue text grant permissions, request secrets, or bypass review. Restrict tokens and runner access to the minimum needed, and use human approval for sensitive workflows or untrusted contributions.
Make outcomes visible on the issue. Have the runner comment with a short status, what it changed, checks it ran, and links to the branch or pull request. On success, open a pull request that references the issue and move the issue to agent:review. Do not mark the issue completed merely because code was generated; completion should follow the repository’s normal review and merge process.
Handle failure as a queue state, not a silent retry. If the task cannot be completed, leave a concise comment explaining the blocker and useful diagnostic details, then apply agent:blocked or return it to ready according to a documented retry policy. Avoid endless immediate retries: cap attempts, add a delay or require a human to re-approve repeated failures, and preserve logs without posting secrets.
Test the full loop with a harmless issue. Start with a small task in a non-production repository or a low-risk branch. Confirm that the workflow selects the intended issue, claims it once, creates a pull request, updates labels, and handles an intentional failure. Check permissions, duplicate-run behavior, and what happens when an issue is closed or edited mid-run before enabling regular unattended processing.
Review and maintain the queue. Triage new issues, keep acceptance criteria current, and periodically inspect stale working items, blocked tasks, and failed runs. Decide who may add the ready label and what happens when a task is no longer wanted. Close or relabel obsolete issues rather than relying on the agent to infer that they should be ignored.

Common Mistakes

Using vague issues: “Improve performance” is not a reliable unattended task. Define a measurable target or ask for an investigation report with a specific scope.
Allowing overlapping runs: A scheduled workflow can start again before its previous run finishes. Add concurrency control and re-check the issue state before writing.
Giving broad credentials: A queue does not make untrusted issue instructions safe. Limit token permissions, isolate execution, and require review for changes.
Treating a label as proof of completion: A pull request can fail checks or need changes. Keep the issue open until the normal completion condition is met.
Retrying without limits: Repeated runs can waste resources and create duplicate branches or comments. Track attempts and make retries deliberate.

Tips

Use stable labels with a short prefix so queue states are easy to filter and distinguish from ordinary project labels.
Make the agent’s issue comment a compact audit trail: run link, branch or pull request, checks, and next action.
Keep a human approval step for ambiguous tasks, dependency changes, deployments, or operations with meaningful side effects.
Prefer idempotent workflow actions: rerunning should detect an existing branch or pull request instead of creating duplicates.
Set a maximum runtime and define what happens when the runner times out, including how the issue is released or marked for investigation.

Troubleshooting

No issues are picked up: Check that the workflow is enabled, its trigger has occurred, the issue is open, and the label spelling and repository filter match. Verify that the workflow token can read issues and that any approval gate is satisfied.

Two runs work on one issue: Inspect workflow concurrency settings and the timing of the claim step. Ensure the lock covers selection through claim, and make the runner stop if the issue is no longer eligible. Clean up duplicate branches or pull requests manually before retrying.

The agent cannot open a pull request or update labels: Review the workflow token’s repository permissions and any organization policy that restricts automation. Grant only the required permissions, then rerun a low-risk test. Do not solve permission errors by exposing a broad personal token.

The run fails or appears stuck: Check the workflow run logs and runner limits, then inspect the issue for its last status comment. If the worker ended before updating the issue, reconcile the label manually and record what happened. Retry only after confirming that no active run or partial pull request remains.

The result does not meet the issue requirements: Ask for a focused revision on the pull request or clarify the issue’s acceptance criteria. Keep review and testing in the normal development process; queue status is not evidence that the change is correct.

Frequently Asked Questions

Why use GitHub Issues instead of a separate queue?
Issues provide durable task descriptions, discussion, labels, history, and links to pull requests in the same project. They are suitable when the required queue volume and workflow fit the repository’s existing process.

Should the agent assign issues to itself?
It can, but assignment is optional. A working label plus a comment that identifies the run is often clearer; use assignment only if your team already treats it as ownership.

Can an agent merge its own pull request?
For an unattended workflow, keeping merge approval separate is safer. Require the repository’s normal human review and checks unless your organization has explicitly designed and approved an automated merge policy.

What should happen when an issue changes during a run?
Re-fetch the issue before creating or updating a pull request. If its requirements changed or it was closed, stop and report the mismatch instead of silently acting on stale instructions.

How do I avoid duplicate work after a retry?
Use a stable branch or run identifier, check for an existing pull request linked to the issue, and make workflow updates idempotent. Resolve any partial work before starting a fresh attempt.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.