AW Admission Service Specification | GitHub Agentic Workflows
Skip to main content AW Admission Service Specification Version : 1.4 draft Status : gh-aw client implemented; admission authority deployed separately Date : 2026-10-20 The terms MUST, MUST NOT, SHOULD, and MAY indicate normative requirements. This repository implements the gh-aw client and compiler integration. The admission authority, trusted accounting ingestion, provisioning, and backend claim verification remain deployment-owned services; the contracts below apply to both sides.
1. Scope and Ownership Section titled “1. Scope and Ownership” The compiler MUST omit admission code by default. Set "admission": true in .github/workflows/aw.json to generate the admission check in activation and callback in conclusion for all workflows. An explicit repository admission boolean takes precedence over workflow frontmatter on.admission ; absent either setting, the default is false . When the effective setting is false , the compiler MUST omit both steps and admission outputs without changing either job’s permissions.
Changing these settings requires recompilation. The check runs after activation setup and before author pre-steps, daily validation and agent execution. Only validated results and component allowances propagate to downstream jobs; credentials, request identity and service diagnostics remain client-local. Without a configured endpoint, an explicit step if skips admission, and activation continues through its existing fallback checks.
A deployment-selected admission authority server (the authority) MUST implement the HTTPS admission service, trusted usage ingestion, policy evaluation, and protected operator diagnostics. It MAY use a server-side GitHub App for backend verification and configuration provisioning. The compiler MUST record the effective compile-time setting as an explicit admission boolean in gh-aw-manifest , including false when disabled.
This field indicates whether admission integration is generated, not whether a runtime endpoint is configured or a run is admitted. The gate is a cooperative admission check for participating workflows, not an unbypassable organization policy or hard spending cap. It decides whether an AW execution may start and returns runtime maximum AI Credits: a required primary allowance and optional, independent threat-detection and evals allowances.
A validated allowance overrides that component’s configured or default runtime limit, rather than adding to it or taking the minimum. Omitted optional allowances preserve existing component policy. Correlation uses the caller’s W3C traceparent , not a response trace or correlation ID. This is not a billing API, spend-inspection endpoint, inference proxy, or mid-execution cancellation mechanism. The compiler-owned callback step inside conclusion provides the corresponding completion notification after full unified-session artifact upload and its retry finish.
The callback reads a size-bounded compact projection directly from the local session and receives artifact IDs from preceding step outputs, then posts them to /api/conclusion . No extra job or compact-session job-output handoff is needed. The authority can process the compact metadata immediately and resolve the full session through GitHub without polling or waiting for a workflow-completion webhook. This is end-of-session delivery, not a live event stream while the agent runs.
It neither authorizes execution nor settles billing. Delivery is best-effort and does not change completed agent or safe-output results. The protocol uses REST POST with a JSON body, authenticated exclusively by a GitHub Actions OIDC identity token with an audience restricted to the intended authority deployment. The client MUST NOT send GITHUB_TOKEN , a PAT, Copilot token, GitHub App JWT, installation access token, App private key, API key, or custom activation credential to the admission service.
The feature MUST support only this protocol, with no GET, alternate authentication mode, negotiation, or credential fallback. OIDC Token Broker Contract Section titled “OIDC Token Broker Contract” The token broker is independent of admission. Its normative server and client contracts, capability authorization, issuance requirements, compliance tests, and implementation limitations are defined in the Token Broker Specification .
Admission success or an ignored admission outage does not authorize token issuance or permit broker authentication to fail open. 2. Configuration and Provisioning Section titled “2. Configuration and Provisioning” Managed Environment Variables Section titled “Managed Environment Variables” Admission endpoint, audience, and outage configuration MUST come exclusively from managed GitHub Actions variables, resolved at workflow runtime and passed to the admission step as environment variables.
Repository JSON files and workflow/frontmatter configuration MAY enable code generation as specified above, but MUST NOT define or override these runtime settings. The compiler MUST register these variables with the existing gh aw env get/update mechanism: Actions variable Managed YAML field Built-in fallback GH_AW_DEFAULT_ADMISSION_URL default_admission_url Empty; gate disabled GH_AW_DEFAULT_ADMISSION_AUDIENCE default_admission_audience Effective endpoint URL GH_AW_DEFAULT_ADMISSION_ON_OUTAGE default_admission_on_outage ignore The corresponding managed-defaults YAML is: default_admission_url : https://admission.example.org/api/admission default_admission_audience : https://admission.example.org/api/admission default_admission_on_outage : ignore The service route is /api/admission ; the deployment origin is configurable.
A nonempty URL MUST be the full absolute HTTPS URL for that route, without embedded credentials, query parameters, fragments, or GitHub Actions expressions. A nonempty audience MUST be a literal deployment-specific value without control characters or expressions. It identifies the intended recipient; it is not a secret or a GitHub App identifier. The conclusion route MUST be /api/conclusion on that same configured origin, including any explicit port.
It MUST NOT have an independently configurable destination or audience. Both operations use the effective admission audience; when the audience is unset, its fallback remains the configured /api/admission URL, not the derived conclusion URL. An empty endpoint disables both operations before token acquisition. Each effective runtime variable takes precedence over its built-in fallback; repository Actions variables override organization variables.
Enterprise-wide rollout provisions organization variables in each enrolled organization, not an assumed native enterprise Actions-variable scope. Compiler-process environment variables MUST NOT determine these values, and workflow-local configuration MUST NOT introduce another runtime override layer. A configured endpoint enables admission only in workflows compiled with admission steps. An unset or empty endpoint makes the check a no-op; an audience or outage policy alone MUST NOT enable it.
A nonempty but invalid endpoint MUST fail validation, not silently disable the check. flowchart TD V["Managed variables<br/>repository over organization"] --> E{"Effective endpoint"} E -->|Empty| S["Skip admission"] E -->|Invalid| B["Fail activation"] E -->|Valid| C["Validate remaining settings<br/>and check authority"] When admission is compiled in, the compiler MUST emit the runtime variable hooks, so enabling, disabling, or changing managed runtime settings does not require recompilation.
An empty endpoint does not remove job-wide OIDC permission from activation or conclusion. Existing managed-default update semantics remain unchanged: omitted or null YAML fields delete the corresponding variable at the selected scope. Operators MUST preserve other defaults when updating a defaults file. Managed variables distribute configuration, not locked policy. Repository Actions variables override same-named organization va
The rest of this page is on the live site.