Authentication | GitHub Agentic Workflows
Skip to main content Authentication This page describes authentication settings for GitHub Agentic Workflows. Two kinds of authentication are needed Authentication for model inference for your chosen AI engine. Authentication for GitHub API operations, safe outputs and other GitHub operations. Authenticating your AI Engine Section titled “Authenticating your AI Engine” Configure the authentication method your AI engine needs before running your first workflow.
Copilot (default) Section titled “Copilot (default)” Recommended: permissions: copilot-requests: write — uses the GitHub Actions token; no PAT required, billing through your org Alternative: COPILOT_GITHUB_TOKEN — fine-grained PAT with Copilot Requests permission Notes: When copilot-requests: write is set, COPILOT_GITHUB_TOKEN is ignored for inference Claude Section titled “Claude” Standard: ANTHROPIC_API_KEY — static API key from Anthropic Console Keyless alternative: engine.auth Anthropic WIF — short-lived OIDC token via federation rule; no long-lived secret on the repo Codex Section titled “Codex” Standard: OPENAI_API_KEY or CODEX_API_KEY ; the runtime checks CODEX_API_KEY first Keyless alternative: Azure Entra OIDC through the AWF API proxy Keyless alternative: OpenAI Workload Identity Federation through the AWF API proxy Gemini Section titled “Gemini” Standard: GEMINI_API_KEY — static API key from Google AI Studio Keyless alternative: engine.auth Google WIF — short-lived OIDC token via Google Cloud Workload Identity Federation; no long-lived secret on the repo Pi Section titled “Pi” Default Copilot backend: permissions: copilot-requests: write or COPILOT_GITHUB_TOKEN anthropic/ model: ANTHROPIC_API_KEY openai/ or codex/ model: CODEX_API_KEY or OPENAI_API_KEY Notes: Pi selects authentication from the provider prefix in model: .
See Using Pi with GitHub Agentic Workflows . Most workflows need one AI engine authentication path. Additional GitHub operations may require separate credentials. Additional Authentication Section titled “Additional Authentication” Some workflows need additional authentication. These can be tokens added as secrets and referenced in your workflow, or GitHub App can be used. Workflows using the following read operations from GitHub require Additional Authentication for GitHub Tools , via either a secret containing a PAT or GitHub App: Read from multiple repositories Read from projects GitHub tools remote mode Workflows using the following features of Safe Outputs require additional authentication, via either a secret containing a PAT or GitHub App: Safe outputs writing cross-repo Safe outputs assigning Copilot coding agent to issues/PRs Safe outputs updating GitHub Projects Safe outputs triggering CI on PRs Workflows using custom MCP tools or safe outputs may require additional authentication depending on the operations performed.
How do I add a GitHub Actions secret to my repository? Section titled “How do I add a GitHub Actions secret to my repository?” You can add secrets manually in the GitHub UI or use the CLI for a streamlined experience. Adding secrets using the CLI Section titled “Adding secrets using the CLI” Terminal window gh aw secrets set COPILOT_GITHUB_TOKEN --value " YOUR_COPILOT_PAT " You can also check existing secrets with: Terminal window gh aw secrets bootstrap If you’re working in Codespaces, use the GitHub UI method below to add secrets.
Adding secrets using the GitHub UI Section titled “Adding secrets using the GitHub UI” Go to your repository on GitHub Click on “Settings” → “Secrets and variables” → “Actions” Click “New repository secret” and add the token name and value GitHub Actions secrets for AI engines Section titled “GitHub Actions secrets for AI engines” A reference for all GitHub Actions secrets used by GitHub Agentic Workflows for AI engine authentication: copilot-requests: write permission Section titled “copilot-requests: write permission” The recommended way to authenticate Copilot inference is to grant the copilot-requests: write permission in your workflow.
This uses the built-in GitHub Actions token ( ${{ github.token }} ) — no PAT or repository secret is required. Billing is handled centrally through your organization’s Copilot subscription. Setup : Add copilot-requests: write to the permissions: block of your workflow frontmatter: permissions: contents: read copilot-requests: write When this permission is present, gh-aw automatically uses the GitHub Actions token for Copilot inference.
Any value set for COPILOT_GITHUB_TOKEN or GH_AW_GITHUB_TOKEN is ignored for inference — those tokens are not passed to the Copilot engine. Why this is preferred : No PAT lifecycle management — tokens are minted per-run and automatically revoked. Billing flows through the organization’s Copilot plan, not an individual user’s quota. Works seamlessly in forked repos and organization workflows without sharing a personal token.
COPILOT_GITHUB_TOKEN Section titled “COPILOT_GITHUB_TOKEN” Use COPILOT_GITHUB_TOKEN when you need to authenticate Copilot inference with a specific user’s PAT — for example, in personal repositories or when centralized org billing is not available. When permissions: copilot-requests: write is set in your workflow, this secret is ignored for inference. When using this PAT-based Copilot authentication path, set a GitHub Actions secret to a fine-grained Personal Access Token (PAT) that can authenticate Copilot CLI.
Setup : Create a fine-grained PAT (this link pre-fills the token name, description, and Copilot Requests permission). Verify the following settings before generating: Resource owner is your user account , not an organization. Under Permissions → Account permissions , Copilot Requests is set to Read . Click Generate token and copy the token value. Add the PAT to your GitHub Actions repository secrets as COPILOT_GITHUB_TOKEN , either by CLI or GitHub UI.
Terminal window gh aw secrets set COPILOT_GITHUB_TOKEN --value " <your-github-pat> " Custom endpoints : To route Copilot CLI through a custom endpoint (e.g., a corporate proxy or GHE Cloud data residency instance), set GITHUB_COPILOT_BASE_URL in engine.env . See Custom API Endpoints via Environment Variables for details. COPILOT_GITHUB_TOKEN must still be a fine-grained PAT — GitHub Apps and OAuth tokens are not supported for this secret. gh-aw also validates token type at runtime in activation: if COPILOT_GITHUB_TOKEN or GH_AW_GITHUB_TOKEN starts with the OAuth token prefix ( gho_ ), the workflow fails early with guidance to replace it with a fine-grained PAT.
OAuth user tokens are intentionally rejected because they are broad user-session credentials and cannot be scoped appropriately for automation. Troubleshooting : If your workflow fails at the Copilot inference step even with the token set, verify that the token owner’s account has an active Copilot license. See Copilot License or Inference Access Issues for a local diagnostic step. GH_AW_GITHUB_TOKEN Section titled “GH_AW_GITHUB_TOKEN” GH_AW_GITHUB_TOKEN is an optional “magic” GitHub Actions secret used as the default fallback token for GitHub operations outside engine inference.
Use it when your workflow needs authenticated GitHub access beyond the default GITHUB_TOKEN , for example: Safe outputs that write to other repositories Safe outputs that trigger CI on pull requests Safe outputs or tools that need broader repo/API access than the default token provides Fallback when github-app.ignore-if-missing: true is used and app secrets are unavailable Fallback chain: custom github-token → secrets.GH_AW_GITHUB_TOKEN → secrets.GITHUB_TOKEN The compiler’s activation job checks configured magic tokens for unsupported OAuth-token formats.
It passes the relevant secrets through step-level environment variables for that validation; workflow authors should not move these compiler-managed values into work
The rest of this page is on the live site.