Text of github.github.com › gh-aw › reference › engines › copilot 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

GitHub Copilot reference | GitHub Agentic Workflows

Skip to main content GitHub Copilot reference For first-time setup, see Using GitHub Copilot . Shared options are in AI engines . Selection and authentication Section titled “Selection and authentication” Copilot is the default engine. Grant copilot-requests: write for organization-billed inference, or supply COPILOT_GITHUB_TOKEN . External providers use BYOK configuration . The default CLI pin is 1.0.103 . The compiler embeds this version and its reviewed checksum-manifest digest in the generated workflow.

Installation prefers that exact version from the trusted runner toolcache; a cache miss downloads and verifies the pinned release instead of selecting a version from the live compatibility matrix. engine.version overrides the default. CLI-only execution is the default. engine.copilot-sdk: true or engine.driver selects SDK mode. Default model routing Section titled “Default model routing” Without a model , engine.model , or engine.model-routing , a Copilot workflow on GitHub Copilot inference uses model routing with goal: cost and mode: auto for its main agent, instead of the auto model.

A nonempty GH_AW_MODEL_AGENT_COPILOT or GH_AW_DEFAULT_MODEL_COPILOT variable bypasses routing at run time, with the agent variable winning. Set top-level model-routing: false to opt out without pinning a model. BYOK providers aren’t routed by default. Capabilities and limitations Section titled “Capabilities and limitations” Copilot supports engine.agent , custom harnesses, max-continuations , bare mode, and per-command bash allowlists.

Compilation rejects native tools.web-search and CLI-mode tools.web-fetch ; use MCP instead. SDK mode provides a proxy-aware web-fetch tool. Offline BYOK disables native web tools. Sandboxed CLI sessions derive URL approvals from finalized AWF network rules, including network_allowed additions. Domain rules cover apex/subdomains and HTTP/HTTPS unless restricted by protocol/port. These approvals do not grant shell access or bypass the firewall.

Copilot resolves model aliases before launch. Exact IDs pass through unchanged; unavailable IDs fail the first inference request. Dynamic workflows Section titled “Dynamic workflows” Copilot dynamic workflows are experimental and disabled by default. Current CLI releases require both settings: engine : id : copilot dynamic-workflows : true args : [ " --experimental " ] gh-aw enables EXTENSIONS , loads project extensions, and pre-approves workflow runs.

SDK sessions honor the same switch. Store definitions in .github/extensions/<name>/extension.mjs and request the registered workflow by name in the prompt. Their agents retain workflow tool/sandbox restrictions. Availability also depends on the Copilot account; enabling extensions does not make them available with BYOK. The trusted activation snapshot recursively restores .github/ after agent checkouts, even with PR checkout disabled, preventing PR-head extensions/settings/hooks from replacing trusted definitions.

Use ambient-folders for support files elsewhere. Without dynamic workflows, project extensions are not loaded, runs are denied, and configuration restoration occurs only when PR checkout requires it. See the dynamic workflow example . Copilot release checksum pins Section titled “Copilot release checksum pins” To download a Copilot CLI version not covered by the setup action’s built-in pins, provide engine.checksums-sha256 alongside engine.version : engine : id : copilot version : " 1.0.101 " checksums-sha256 : " 018625eac68670d66ede904b9b82cdcd6ab8f87ba20e6e1fbdf0b62c8295d5be " The example uses the manifest digest for v1.0.101; change both fields together for another release.

The digest authenticates SHA256SUMS.txt , not an individual platform archive. It must be a literal string of exactly 64 lowercase hexadecimal characters obtained through an independently trusted channel. Fetching a checksum from the same potentially intercepted origin as the executable is not independent authentication. An explicit pin overrides the built-in manifest pin and bypasses the runner toolcache. Both the host archive and a requested musl guest archive are verified against the authenticated manifest.

Omit command , which replaces the built-in installer. This field is only supported by the built-in Copilot CLI installer, not other engines or inline engine definitions. The engine’s version and pin are inherited by detection and eval jobs that reuse that engine. A separate safe-outputs.threat-detection.engine override accepts its own version and checksums-sha256 . For AWF, use sandbox.agent.checksums-sha256 . The compiler supplies the reviewed digest automatically when engine.version is omitted or matches the compiler’s default version.

These generated installs pass --prefer-toolcache : the pin authenticates downloaded archives, not the cached host binary. A musl guest archive is still downloaded and verified when the host uses cache. User-supplied frontmatter pins continue to bypass the toolcache. Compilation fails if the compiler’s default version or digest is missing or malformed. Other versions without an explicit pin retain the trusted toolcache policy and setup action’s built-in release pins; an unreviewed download still fails closed.

A frontmatter pin requires a literal semantic release version such as "1.0.101" or "v1.0.101" ; it cannot be combined with latest , an omitted version, or a version expression. For maintainers, pkg/constants/version_constants.go stores DefaultCopilotVersion and DefaultCopilotChecksumsSHA256 together. bash scripts/update-copilot-version.sh VERSION resolves both from the reviewed pin table, without downloading or trusting new release data.

New releases must first be authenticated and added with scripts/update-release-pins.sh ; the resolver refuses releases without a reviewed pin. Copilot Custom Configuration Section titled “Copilot Custom Configuration” Use agent to reference a custom agent file in .github/agents/ (omit the .agent.md extension): engine : id : copilot agent : technical-doc-writer # .github/agents/technical-doc-writer.agent.md See Copilot Agent Files for details.

Copilot Bring Your Own Key (BYOK) Mode Section titled “Copilot Bring Your Own Key (BYOK) Mode” The Copilot engine supports routing requests to an external LLM provider instead of GitHub’s default routing. This is useful when you want to use a different model or provider (e.g., OpenAI, Anthropic, Azure OpenAI, or a local Ollama/vLLM instance) while still using the Copilot CLI tooling. Set COPILOT_PROVIDER_BASE_URL in engine.env to activate BYOK mode.

The credential variables COPILOT_PROVIDER_BASE_URL , COPILOT_PROVIDER_API_KEY , and COPILOT_PROVIDER_BEARER_TOKEN are explicitly allowed to carry ${{ secrets.* }} references in engine.env under strict mode — they are not leaked to the agent container. Other COPILOT_PROVIDER_* variables hold non-sensitive configuration and can be set as plain strings. When COPILOT_PROVIDER_BASE_URL is a literal URL, gh-aw automatically adds its provider hostname to the AWF allow-list for both the main agent run and the threat-detection Copilot step, and the threat-detection step now derives its Copilot API target from that literal BYOK URL even when engine.api-target and GITHUB_COPILOT_BASE_URL are unset.

When it is supplied via a secret or variable expression, add the provider hostname explicitly to network.allowed so the threat-detection step can reuse that concrete host safely. Variable Required Description COPILOT_PROVIDER_BASE_URL ✓ for BYOK Base URL of the external provider (e.g. https://api.openai.com/v1 or https://RESOURCE.openai.azure.com/openai/v1 for Azure Foundry OpenAI) COPILOT_MODEL ✓ for BYOK Model to use (e.g. claude-sonnet-4 , gpt-4o ); required by most providers COPILOT_PROVIDER_API_KEY Optional API key for cloud providers (OpenAI, Anthropic, etc.); not needed for local providers COPILOT_PROVIDER_BEARER_TOKEN Optional Bearer-token alternative to COPILOT_PR

The rest of this page is on the live site.