Text of github.github.com › gh-aw › specs › token-broker-specification 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

Token Broker Specification | GitHub Agentic Workflows

Skip to main content Token Broker Specification Version : 1.0.0 Status : Experimental draft Date : 2026-10-30 Editors : GitHub Agentic Workflows maintainers Latest version : Token Broker Specification Abstract Section titled “Abstract” This specification defines a deployment-owned HTTPS service that exchanges a verified GitHub Actions OpenID Connect (OIDC) identity token for a short-lived credential. Two independent capabilities authorize GitHub Copilot inference requests and Copilot coding-agent task operations.

The specification defines the wire contract, issuer verification, tenant and workflow authorization, credential issuance, renewal, failure handling, and compliance tests. It does not define a public GitHub credential-minting API or supply a server implementation. Status of This Document Section titled “Status of This Document” Token broker authentication is experimental. The protocol, configuration, and behavior may change without deprecation.

Compiling a workflow that enables either broker capability emits an experimental-feature warning. This is a project specification following W3C-style conventions, not a W3C Recommendation. Repository maintainers govern changes through the normal contribution and review process. Version numbers follow semantic versioning: incompatible contract changes increment the major version, backward-compatible features increment the minor version, and clarifications increment the patch version.

Implementation status (informative): Partial integration. The shared client supports both token types. Coding-agent task creation and issue-assignment integrations obtain credentials at request time and renew them as necessary. Brokered Copilot inference is wired for the bounded detection and evals jobs. Main-agent inference remains blocked on a renewable AWF credential provider. The compiler rejects broker-enabled GitHub-backed inference in the main agent job, including applicable fallback models; this is not limited to the engine named copilot .

A successful standalone copilot-request exchange does not establish working cloud inference. Full end-to-end acceptance has not been achieved. Server implementation, deployment, and issuer integrations remain deployment-owned. Table of Contents Section titled “Table of Contents” Introduction Conformance Runtime configuration and trust boundaries Exchange protocol Identity verification and authorization Credential issuance and lifecycle Compliance testing References Appendices Change log 1.

Introduction Section titled “1. Introduction” 1.1. Purpose and scope Section titled “1.1. Purpose and scope” The broker removes the need to distribute long-lived capability credentials to participating workflows. It accepts a GitHub-signed job identity, applies deployment policy, and returns only a credential and its expiration. A capability is an operation class identified by token_type . A tenant is a deployment-enrolled security boundary bound to stable GitHub owner and repository identities.

An execution context identifies a repository, workflow, run, attempt, and credential-consuming job. An issuer adapter is a trusted server component that obtains a credential from an approved backend. This specification covers broker exchange and its compiler/client integration contract. It does not cover admission decisions, billing, arbitrary GitHub authentication, provider endpoint discovery, deployment provisioning, or a new secret store.

The admission service remains independent. 1.2. Design goals (informative) Section titled “1.2. Design goals (informative)” The protocol deliberately excludes caller-selected scopes, tenant IDs, resource URLs, and provider endpoints. The server derives authority from verified identity and enrolled policy, not from caller assertions. Capabilities remain independent so that a deployment can enable only the operations it can securely issue.

2. Conformance Section titled “2. Conformance” 2.1. Requirements notation Section titled “2.1. Requirements notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 . Sections 2–7 and Appendix C are normative except where explicitly marked informative.

The introduction, implementation status, examples, references, deployment decisions, and change log are informative. Requirements apply to the named actor; a server-only implementer is not responsible for implementing the compiler. 2.2. Conformance classes Section titled “2.2. Conformance classes” Class Requirements Broker server Satisfies all server requirements, including rejection and isolation requirements, for its declared capability set.

Compiler and runtime client Satisfies configuration, transport, response-validation, caching, and credential-handling requirements. Integrated deployment Combines conforming components and demonstrates actual downstream use and renewal for each claimed capability. A broker MUST declare its supported capability set to operators. The set MAY contain either capability, both, or neither. An empty set can conform to the exchange and rejection protocol but cannot claim usable credential issuance.

Omission of an optional capability is not partial conformance. An implementation failing a mandatory requirement MUST NOT claim conformance. These are role-based classes, not escalating Basic/Standard/Complete levels. Inference and task support are independent, not tiers. Conformance claims MUST identify the specification version, class, supported capabilities, and test results. Client unit tests alone MUST NOT be presented as server or integrated-deployment certification.

3. Runtime Configuration and Trust Boundaries Section titled “3. Runtime Configuration and Trust Boundaries” Workflow source MUST explicitly select one or both capabilities using token-broker.copilot-request: true and/or token-broker.copilot-task: true . Omission MUST preserve existing authentication. An inherited broker URL alone MUST NOT enable workflow-handler broker authentication. copilot-request MUST NOT be combined with permissions.copilot-requests: write .

For opted-in task consumers, the compiler MUST carry the reserved member _token_broker: {"copilot-task": true} in the existing GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG JSON object. Workflow handlers MUST enable broker authentication only when this member selects copilot-task as boolean true ; missing, false, malformed, or string-valued markers MUST NOT enable it. This marker introduces no new environment variable. A selected capability with a missing or empty GH_AW_TOKEN_BROKER_URL MUST fail closed when a credential is requested, rather than disable broker authentication or select a legacy credential.

The explicit low-level getToken(tokenType) exchange API is marker-independent. A caller invoking it directly requests an exchange, subject to URL validation and all protocol requirements. The marker gates workflow-handler integration, not the broker server or this low-level API. The compiler MUST emit the single endpoint environment variable GH_AW_TOKEN_BROKER_URL , resolved at Actions runtime using: GH_AW_TOKEN_BROKER_URL : ${{ vars.GH_AW_TOKEN_BROKER_URL || secrets.GH_AW_TOKEN_BROKER_URL }} Organization/repository Actions variables and secrets supply this setting through existing Actions resolution rules.

The compiler MUST NOT read a deployment URL from its own environment or embed a resolved deployment URL in generated YAML. There is no separate audience, capability-specific URL, or provider-endpoint setting in this protocol. The endpoint MUST be an absolute HTTPS URL with a hostname and without user information, fragments, whitespace, or backslashes. An enabled credential request with a missing, empty, or invalid URL MUST fail closed.

The configured URL string, including any path or query,

The rest of this page is on the live site.