Authentication

This page describes authentication settings for GitHub Agentic Workflows.

Authenticating Your Coding Agent (AI Engine)

You will need one of the following GitHub Actions secrets configured in your repository to authenticate the AI engine you choose:

• Copilot – Add COPILOT_GITHUB_TOKEN
• Claude by Anthropic – Add ANTHROPIC_API_KEY
• Codex by OpenAI – Add OPENAI_API_KEY
• Gemini by Google – Add GEMINI_API_KEY

Most workflows will run without any additional secrets or additional authentication.

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
• GitHub tools lockdown 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?

You can add secrets manually in the GitHub UI or use the CLI for a streamlined experience.

Adding secrets using the CLI

gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_COPILOT_PAT"

You can also check existing secrets with:

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

1. Go to your repository on GitHub
2. Click on “Settings” → “Secrets and variables” → “Actions”
3. Click “New repository secret” and add the token name and value

GitHub Actions secrets for AI engines

A reference for all GitHub Actions secrets used by GitHub Agentic Workflows for AI engine authentication:

COPILOT_GITHUB_TOKEN

If using Copilot as your AI engine, you need a GitHub Actions Secret set to a GitHub Personal Access Token (PAT) to authenticate Copilot CLI.

Setup:

Create a fine-grained PAT:

1. Select your user account, not an organization.

2. Choose Public repositories, even if you will be using it with private repositories. This is required for the “Copilot Requests” permission to be available.

3. Click Add permissions and choose Copilot Requests.

4. Click Generate token and copy the token value.

5. Add the PAT to your GitHub Actions repository secrets as COPILOT_GITHUB_TOKEN, either by CLI or GitHub UI.

   gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-github-pat>"

Creating a fine-grained PAT for user-owned repositories with Copilot permissions

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.

---

ANTHROPIC_API_KEY

If using the Claude by Anthropic engine, you need to set a GitHub Actions secret ANTHROPIC_API_KEY to be an API key from Anthropic.

Setup:

1. Create an API key at https://platform.claude.com/docs/en/get-started

2. Add it to your repository secrets, either by CLI or GitHub UI:

   gh aw secrets set ANTHROPIC_API_KEY --value "YOUR_ANTHROPIC_API_KEY"

See also Using Claude Code for additional configuration needed when using Claude with GitHub MCP.

---

OPENAI_API_KEY

If using the Codex by OpenAI engine, you need to set a GitHub Actions secret OPENAI_API_KEY with an API key from OpenAI.

Setup:

1. Create an API key at https://platform.openai.com/api-keys

2. Add it to your repository secrets, either by CLI or GitHub UI:

   gh aw secrets set OPENAI_API_KEY --value "YOUR_OPENAI_API_KEY"

See also Using Codex for additional configuration needed when using Codex with GitHub MCP.

---

GEMINI_API_KEY

If using the Gemini by Google engine, you need to set a GitHub Actions secret GEMINI_API_KEY with an API key from Google AI Studio.

Setup:

1. Create an API key at https://aistudio.google.com/api-keys

2. Add it to your repository secrets, either by CLI or GitHub UI:

   gh aw secrets set GEMINI_API_KEY --value "YOUR_GEMINI_API_KEY"

See also Using Gemini for additional configuration needed when using Gemini with GitHub MCP.

---

Using a GitHub App for Authentication

For enhanced security with short-lived tokens, you may configure a GitHub App instead of using PATs.

This does not apply to COPILOT_GITHUB_TOKEN, which must currently be a PAT. A single GitHub App can be used for all other GitHub authentication needs in GitHub Agentic Workflows, including tool authentication and safe outputs.

After creating your app, configure it in your workflow:

permissions:
  contents: read
  issues: read

tools:
  github:
    mode: remote
    toolsets: [repos, issues, pull_requests]
    app:
      app-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}
      owner: "my-org"                    # Optional: defaults to current repo owner
      repositories: ["repo1", "repo2"]   # Optional: defaults to current repo only

Make sure you set up repository variables and secrets:

gh variable set APP_ID --body "123456"
gh aw secrets set APP_PRIVATE_KEY --value "$(cat path/to/private-key.pem)"

At workflow start, a token is automatically minted with permissions matching your job’s permissions: field. The token is passed to the GitHub MCP server and automatically revoked at workflow end (even on failure).

You can also use GitHub App tokens for safe outputs operations:

safe-outputs:
  app:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
    owner: "my-org"                    # optional: installation owner
    repositories: ["repo1", "repo2"]   # optional: scope to specific repos
  create-issue:

When you configure app: for safe outputs, tokens are minted with permissions specific to the safe output operations being performed, rather than the broader job-level permissions. This provides enhanced security by ensuring that tokens have the minimum necessary permissions for their specific use case.

For both tool authentication and safe outputs, you can scope the GitHub App token to specific repositories for enhanced security. This limits the token’s access to only the repositories it needs to interact with.

• Omit repositories field - Current repository only (default)
• repositories: ["*"] - Org-wide access (all repos in the installation)
• repositories: ["repo1", "repo2"] - Specific repositories only

---

Related Documentation

• Engines - Engine-specific authentication
• Safe Outputs - Safe output token configuration
• Tools - Tool authentication and modes
• Permissions - Permission model overview