DENGEL / DOCS

Workflow states, errors, and Receipts

Use this reference to interpret records returned by the CLI and API. For a first workflow, see managed Build or Guard with your own agent.

Managed Build states

Read the summary from GET /v1/runs and the current record from GET /v1/runs/{id}. Track the lifecycle, workflow disposition, and verification verdict separately.

Field Values and meaning
lifecycle define, approve, build, verify, deliver, closed. This is the stage. A closed run can have several outcomes, including cancellation.
disposition ready, needs_specification, working, repairable, blocked, needs_human_judgment, rejected, rollback_recommended, canceled, or superseded. This describes the workflow's next step or outcome.
verdict not_evaluated before verification, verified when all required checks pass independently on the exact candidate, failed when a required check fails, or inconclusive when required evidence is incomplete.

For a run that needs a decision, read the approval queue or open the run in the panel. A verified verdict describes the candidate's evidence. A signed Receipt is the record of a completed landing.

Guard proposal states

Read the proposal detail and use status together with its separate verdict and disposition.

Status What to do
proposed Review the change and the verification quote. An authorized person can start checks in the panel.
verifying Follow the assigned verification and wait for results.
needs_evidence, inconclusive, failed Review the check results and remediation. Resolve missing evidence or fix the candidate before asking for approval.
candidate_changed, stale_base Read the latest refs. Propose the intended head again. If the base moved, update the change against the new base first.
verified, ready_for_approval Checks passed for the recorded candidate. Wait for ready_for_approval and have the eligible human review and confirm in the panel.
landed, rejected, superseded The proposal landed, was refused or stopped, or was replaced. Read the Receipt for a landed proposal.

When checking a proposal, use the full head commit and proposal digest. Review the quote digest separately from the proposal digest. A new candidate, base, or quote may require new checks or approval.

Errors and retries

Gateway errors that use the v1 error format include kind: "error", api_version: "v1", code, and message. Some endpoints and the Git listener use other response shapes. Use the HTTP status and inspect the body. A successful JSON response can also carry incomplete sources; see the API reference.

HTTP status or code What to check
400 invalid_request or 422 plan_invalid Check the payload, field names, required identifiers, or plan validation message.
401 unauthenticated Check the credential for that host. For the Gateway, obtain a fresh token in the intended workspace.
402 funding_required Ask the authorized human to check the quote and available funding in the panel.
403 forbidden, interactive_required, or listener scope_required Check the role or token scope. For interactive authorization, hand off to the signed-in human.
404 not_found Check the exact ID, active workspace, and feature availability.
409 conflict, stale_base, candidate_changed, quote_changed, or needs_evidence Read the current resource, then resolve the conflict. The Gateway or listener may return different codes for a moved candidate.
409 checks_not_approved Ask a workspace owner or maintainer to approve the repository checks in the panel, then retry the proposal.
429 rate_limited Respect Retry-After when present and back off before retrying.
502 or 503 An upstream or required check may be unavailable. Retry reads with backoff. If a write's outcome is unknown, read back its state before retrying.

When an operation accepts an idempotency key, reuse it with the same request after an ambiguous failure. Refresh identities before authorizing a changed request. Agents should report the refusal, resource ID, and observed state to the human without sharing credentials.

Read a signed Receipt

Fetch the full signed record by its Receipt ID. The Gateway endpoint GET /v1/receipts/{id} returns it at data.receipt. The standalone CLI wraps the Gateway response in its own data field, so dengel --json receipt RECEIPT_ID returns the record at data.data.receipt.

Use jq to extract the record from the CLI response.

dengel --json receipt RECEIPT_ID | jq -e '.data.data.receipt'

The Guard proposal detail shows a Receipt summary when one exists. For Receipt searches, q matches the Receipt ID, bundle, canonical commit, or canonical tree.

Fields What they record
id, bundle, bundle_digest Stable Receipt ID and identity of the exact bundle landed.
target_branch, canonical_commit, canonical_tree The branch moved and the commit and tree recorded after landing.
landed_at, landed_by, approved_by When Dengel landed it and the human approval that authorized the action.
signature, timestamp, canonical_signature Dengel's Receipt signature and, where recorded, the timestamp and separate standing of the commit signature.
verification When present, the tested commit and tree and the per-criterion evidence. Treat a missing historical verification record as unrecorded.
author, approval_context When recorded, the human sponsor and agent attribution, the approval rule, and feedback or accepted risks present at landing.
artifact, deployment_ref Optional artifact or pipeline references. Check deployment status in the deployment system.

Keep the full signed record for audit and compare its canonical commit to a fresh read of the intended repository and branch. If the branch has advanced, check that the Receipt commit is in its history. Use the canonical commit for Git comparison. The recorded tree digest has its own format. For cryptographic verification, use the trusted Dengel signing key and the Receipt's signing format for your deployment. Fetching a Receipt and checking the remote branch establishes record and branch agreement.