Text of github.github.com › gh-aw › reference › work-queue as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Work queues | GitHub Agentic Workflows

Skip to main content Work queues tools.work-queue provides a native, Git-backed queue with fair scheduling and task dependencies. The version-3 transaction log, work-queue.jsonl , is authoritative. The default queue branch is work-queue ; Issues can mirror tasks but cannot store the queue. There is no storage option. For architecture, a minimal deployment example , and lightweight alternatives, see WorkQueueOps . The protocol specification and executable models cover implementation contracts and verification.

Initialization and authorization Section titled “Initialization and authorization” The first accepted producer submission atomically installs Policy and Work. Compilation, activation, reads, and dispatch-only requests do not initialize a queue. On an existing AW-managed queue, trusted submission and dispatch processing install missing configured pools and worker profiles on demand before deployment synchronization.

Publish the worker Markdown and compiled lock to the default branch, add any pool to aw.json , and recompile the producer or dispatcher. No manual registration or drain is needed for these additions. Installation publishes a separate PoolInstall operation. New workers must be singleton, repository-scoped AW workflows with verified default-revision source, a matching compiled contract, and active native registration. config_ref records that immutable revision; it is provenance, not authorization.

Existing profiles, deployments, pool limits, default selection, accepted Work, Claims, fairness debt and the Policy epoch are preserved. Workers, observers, dry-run previews, and accepted-request recovery do not install pools or profiles. Changes to installed authority or scheduling economics still require a quiescent queue and an explicit administrator policy update. Native submit-work and submit-graph resolve scheduling and approved AW worker routes from the verified repository revision, not an unrelated local checkout.

Assignment-capable workers must already be published. AW supplies authenticated roles, worker routes, and credentials. Agents receive an immutable snapshot, not queue-write credentials. Workers must accept work_queue_assignment and be verifiable at an approved immutable revision. Queue Git access uses isolated storage and ephemeral authentication, independently of source-checkout credentials. Record Meaning Work Immutable task definition, optionally part of a dependency graph.

Claim Authorization for one attempt, identified by its original claim_handle . Policy Scheduling limits and approved worker contracts. Deployment Worker revision and availability for future execution. Reservation Worker capacity retained until verified termination or nonlaunch. Completion Durable task completion, recorded before delivering effects. Result Independently verified delivery; satisfies Work dependencies. Release Frees a reservation; does not establish Result.

An existing malformed, policyless, or unsupported ledger fails validation rather than being reset. Git access failures have no REST/GraphQL ledger fallback. Repository scheduling settings Section titled “Repository scheduling settings” Configure the optional work_queue object in .github/workflows/aw.json . A missing file, missing section, or {} uses defaults. Unknown properties, nulls, invalid types, and out-of-range values are errors.

Identities, credentials, and worker routes are managed by AW, not this object. Field Default Accepted values concurrency 16 Integer 1–4,096; capacity per pool pending_limit 4,096 Integer 1–4,096; queue-wide pending Work retry.max_attempts 3 Integer 1–16 retry.backoff_seconds 30 Integer 1–3,600 mode weighted-priority weighted-priority or strict-priority class_weights [8,4,2,1,1] Five integer weights, each 1–1,000 accounting_weights {"":1} Named integer weights, each 1–1,000; the empty key retains weight 1 pools One default pool Up to 64 named objects overriding concurrency , retry , and per_account_limit (1–4,096); inherit AW worker routes issues Disabled Boolean or settings object; see Backing Issues .github/workflows/aw.json { "work_queue" : { "concurrency" : 3 , "pending_limit" : 30 , "retry" : { "max_attempts" : 3 , "backoff_seconds" : 30 } } } Defaults use singleton assignments and FIFO ordering within one priority and accounting key.

Weights allocate opportunities to receive durable Claims, not CPU time or successful completions. Lower priority numbers receive greater weight by default, not strict precedence. Editing configuration does not replace an installed Policy. Apply economic changes with policy --from-config --epoch EPOCH only when no unfinished Work, reservations, or unresolved delivery barriers remain. Worker evolution Section titled “Worker evolution” Compatible worker updates affect future execution without draining the queue.

Contracts cover declared inputs, permissions, tools, and output/resource capabilities; prompt or engine changes alone do not change the contract. Existing assignments retain their original worker profile and run binding. Unavailable or incompatible workers block only affected Work and its successors. Protected producer/dispatcher processing synchronizes approved routes from the verified default-branch revision. Operators use deploy --from-config , optionally with --pool or --worker-profile .

To pin Work, use submit-work --execution-ref IMMUTABLE_SHA or a submission node’s execution_ref ; changing the pin requires new Work. Worker dispatch uses verified tags named gh-aw/work-queue/<SHA> . The trusted dispatch credential needs actions: write and contents: write for tag creation. Tags are never overwritten or deleted by the queue; repository writers must not mutate tags in use. A launch sends at most one dispatch POST: an uncertain response does not authorize another launch.

Workflow roles and intent tools Section titled “Workflow roles and intent tools” Producer or dispatcher tools : work-queue : true Worker tools : work-queue : require-assignment : true worker : true Dispatchers also declare approved workers in safe-outputs.dispatch-workflow.workflows and bound launches with max . The deployment example combines these declarations. Standalone tools.repo-memory persistence is unsupported in native queue workers; memory-backed queues are separate alternative patterns .

Role Authority Observer Read/explain the snapshot; no submit, dispatch, or finish authority. Producer/dispatcher Stage task plans and assignment requests within approved pools, routes, and budgets. The scheduler selects Work. Worker Process only its authenticated assignment’s claims array. Missing required assignment input is an error. MCP tool Purpose work_queue_read , work_queue_explain Inspect the immutable activation snapshot; predictions can be stale. work_queue_submit Stage an immutable task or dependency graph. work_queue_dispatch_next Request scheduler-selected assignments from a pool within a limit. work_queue_claim_finish Stage a Claim’s completed or cancelled finish intent.

When listed in <mcp-clis> , invoke tools as work-queue work_queue_read '{}' . These are agent tools, not gh aw work-queue operator subcommands. Staging an intent does not publish it. Claim-scoped effects and delivery Section titled “Claim-scoped effects and delivery” Every safe output and finish intent belongs to an original Claim. Multi-Claim assignments require claim_handle on every message, even if only one Claim remains open.

Only originally single-Claim assignments may omit it. Finish accepts outcome: "completed" or "cancelled" . keep_open defaults to false; true is valid only with "completed" . Retries must preserve both values. Trusted processing records Completion before authorizing effects and Result only after independent delivery verification. Assignment input, a successful Actions run, or an output artifact alone cannot establish authority or Result. keep_open: true makes Work eligible again only after verified delivery.

The rest of this page is on the live site.