Issue Status Reference for Gentic

Every issue in Gentic carries a single status field that describes both where the issue sits in your team’s workflow and what the agent host is doing with it. This page documents every possible value and the transitions between them.

Moving an issue from Draft to Todo is the specific transition that makes it eligible for an agent run. Until you make that change, no host will claim it and no repository is cloned.

Status lifecycle

A typical issue moves through the lifecycle in roughly this order:

draft → todo → queued → in-progress → ready-for-review
                                     ↘ waiting-for-input
                                     ↘ tests-failed / run-failed
                                     ↘ changes-requested → approved → merged

Not every issue visits every status. The host drives the agent-run states, while several review and deployment states are available for manual or external workflow updates.

Pre-work

These statuses cover the period before an agent host has claimed the issue.

Status	Description
`draft`	The issue is being prepared. It is invisible to the host. Use this while you are still writing or refining the body, uploading attachments, or setting blockers.
`todo`	The issue is ready and sits in the unclaimed pool. The next host poll that finds no other pending work will claim it.

Agent running

These statuses indicate a host is actively handling the issue.

Status	Description
`queued`	A host has claimed the issue and is preparing the run — cloning the configured repository, running the project’s setup script, and starting the agent session. This is a short-lived state; if it persists, see Troubleshooting.
`held`	The agent hit a usage or session limit (for example, a Claude Code quota reset or a Codex rate-limit response). The host parses the reset time out of the error and stores it on the issue. Once the reset time has passed, the next poll re-claims the issue automatically — you do not need to do anything.
`in-progress`	The agent session is live. The transcript panel streams assistant output in real time. A successful changed turn may stay in this status for one visible automatic publishing turn when Create PR automatically is enabled.
`waiting-for-input`	The agent has finished without opening a pull request and is waiting for you to send a follow-up message. If the run left unpublished changes, the issue sidebar offers Create PR while the issue is idle.

Review

These statuses cover the period between the agent opening a pull request and the PR being merged. Most transitions in this section are driven by GitHub webhook events — see How GitHub events map to statuses below.

Status	Description
`testing`	Automated tests are running against the pull request. GitHub check webhooks can set this when checks start or are re-run.
`tests-failed`	Automated tests failed for the pull request. GitHub check webhooks can set this when completed checks fail and can add a Gentic-authored follow-up for the agent.
`ready-for-review`	The agent has opened a pull request and it is ready for human review on GitHub.
`reviewing`	Gentic’s Automatic Review is evaluating the pull request — see Automatic Review below.
`changes-requested`	A reviewer (automatic or human) requested changes. When automatic review responses are enabled, Gentic adds the feedback with Gentic attribution and re-queues the same agent session.
`approved`	The pull request was approved — automatically by Automatic Review, or by an explicit Continue with human review. The pull request is ready to merge.

Automatic Review

When a project or issue has Automatic Review enabled, an isolated reviewer agent evaluates each pull request instead of (or alongside) waiting on a human review. This section only covers what’s visible on the Issue; the engine itself is documented in docs/adr/0004-automatic-review-lifecycle-engine.md and its neighbors. Status precedence. When several conditions could apply to a pull request at once, the issue’s status reflects the most actionable one first, in this order: changes-requested (a reviewer — automatic or human — asked for changes) beats tests-failed (CI failed) beats testing (CI still running) beats reviewing (an automatic review attempt is in flight) beats ready-for-review / approved. This precedence is computed in the database and is stable regardless of which webhook or review event arrives first. Timeline. Every step of an automatic review attempt — queued, started, approved, changes requested, an infrastructure failure, or a cycle being superseded by a new push or a human review — appears as its own entry on the Issue’s timeline, each optionally linking to that attempt’s reviewer execution log. Reviewer logs are never appended to Issue chat. Multiple pull requests. An Issue with more than one associated pull request shows each one’s review state independently in the sidebar, plus an aggregate (“2 of 3 pull requests reviewed”). Attempts. Each pull request gets up to three automatic review attempts per review cycle (a cycle covers one line of fix-iteration pushes). A completed attempt (approved, changes requested, or commented) counts against that budget; an infrastructure failure does not — it retries once automatically, and after a second consecutive failure, automatic progress pauses until new code arrives or you intervene. Recovery controls. When automatic progress is paused or blocked, the Issue sidebar offers up to three actions, shown only when they apply:

Retry review — queue a fresh attempt after two trailing infrastructure failures, without waiting for new code.
Continue with human review — accept the current human review as sufficient and stop further automatic attempts.
Start fresh implementation session — abandon an unresumable implementation session (its host was deleted or banned, its agent/model changed, or no session was ever recorded) so the next fix has somewhere to go.

Merge and deploy

Status	Description
`merged`	The pull request has been merged into the target branch. Set automatically when GitHub sends a `pull_request.closed` webhook with `merged: true`.
`deploying`	Reserved for an external deployment workflow that is running the merged changes.
`deploy-failed`	Reserved for an external workflow reporting a deployment failure.
`validating`	Reserved for an external workflow validating deployed changes.

Terminal

Issues in these statuses are no longer active. You can re-open a conversation by sending a new message in the transcript, which moves the issue back to todo and resumes the same agent session with full prior context.

Status	Description
`run-failed`	The agent run ended with an unrecoverable error before opening a pull request. Check agent activity for the error output. Use Retry with… after fixing the underlying cause.
`completed`	The issue has been resolved and all work is done.
`cancelled`	The issue was cancelled before completion, either manually or because the pull request was closed on GitHub without being merged.

How GitHub events map to statuses

If you have configured the GitHub integration with a webhook, Gentic listens for pull request activity on the PR that the agent opened and updates the issue automatically. The mapping is:

GitHub event	Payload condition	Resulting issue status
`pull_request.closed`	`merged: true`	`merged`
`pull_request.closed`	`merged: false`	`cancelled`
`pull_request.reopened`	—	`ready-for-review`
`check_run`	at least one suite is still running	`testing`
`check_run.completed`	all suites completed and any suite failed	`tests-failed`
`check_run.completed`	all suites completed and no suite failed	`ready-for-review`
`check_suite`	at least one suite is still running	`testing`
`check_suite.completed`	all suites completed and any suite failed	`tests-failed`
`check_suite.completed`	all suites completed and no suite failed	`ready-for-review`
`workflow_run`	at least one suite is still running	`testing`
`workflow_run.completed`	all suites completed and any suite failed	`tests-failed`
`workflow_run.completed`	all suites completed and no suite failed	`ready-for-review`
`pull_request_review.submitted`	GitHub’s own review decision for the pull request is `approved` — which GitHub only reports when branch protection requires reviews. With Automatic Review enabled, the Review Cycle decides this instead (see Automatic Review).	`approved`
`pull_request_review.submitted`	`review.state: changes_requested`	`changes-requested`
`issue_comment.created`	comment was left on a pull request	queues a follow-up
`pull_request_review_comment.created`	inline review comment was left on a pull request	queues a follow-up

Gentic matches pull request, review, and comment events to a stored pull-request URL on the issue. For check events, Gentic resolves the pull request from the check’s commit SHA. Active checks can move ready-for-review issues back to testing, and completed checks only update issues still in testing, so late CI results do not overwrite review or merge statuses. Unsupported event types are ignored. To enable this, point a GitHub webhook at https://<your-gentic-host>/api/integrations/github/webhook, subscribe to the Pull requests, Pull request reviews, Pull request review comments, Issue comments, Check runs, and Check suites events, and set the shared secret to match the GITHUB_WEBHOOK_SECRET configured on your Gentic deployment.

Held status and usage limits

The held status is the recovery path for temporary agent outages. When Claude Code or Codex returns a usage-limit, session-limit, rate-limit, or quota error during a run, the host:

Parses a reset time from the error message. Relative (try again in 2h), absolute, and HH:MM (UTC)-style resets are all supported.
Moves the issue to held and stores the parsed reset time.
Skips the issue on subsequent polls until the reset time has passed.
Re-claims the issue automatically once the reset window opens, resuming the same agent session.

If the host cannot parse a reset time out of the error, the run is treated as a run-failed instead so you can intervene manually. You can also cancel a held issue at any time by changing its status to cancelled.

Get Started

Web App

Agent Host

MCP Integration

Guides

Issue Status Reference for Gentic

Status lifecycle

Pre-work

Agent running

Review

Automatic Review

Merge and deploy

Terminal

How GitHub events map to statuses

Held status and usage limits

​Status lifecycle

​Pre-work

​Agent running

​Review

​Automatic Review

​Merge and deploy

​Terminal

​How GitHub events map to statuses

​Held status and usage limits

Status lifecycle

Pre-work

Agent running

Review

Automatic Review

Merge and deploy

Terminal

How GitHub events map to statuses

Held status and usage limits