Skip to content

docs: fix GH_AW_AGENT_TOKEN fallback behavior documentation #14936

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mnkiefer merged 2 commits into from
Feb 11, 2026
Merged

docs: fix GH_AW_AGENT_TOKEN fallback behavior documentation #14936

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
12cbd34
Initial plan
Copilot Feb 11, 2026
4060d7b
docs: clarify GH_AW_AGENT_TOKEN fallback behavior
Copilot Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/aw/actions-lock.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,11 @@
"version": "v2.0.3",
"sha": "e95548e56dfa95d4e1a28d6f422fafe75c4c26fb"
},
"docker/build-push-action@v6": {
"repo": "docker/build-push-action",
"version": "v6",
"sha": "ee4ca427a2f43b6a16632044ca514c076267da23"
},
"docker/build-push-action@v6.18.0": {
"repo": "docker/build-push-action",
"version": "v6.18.0",
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/release.lock.yml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 7 additions & 4 deletions docs/src/content/docs/reference/tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -450,13 +450,18 @@ gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_COPILOT_PAT"
> [!IMPORTANT]
> **Required** if you need to programmatically assign Copilot agents to issues or PRs

Specialized token for `assign-to-agent:` safe outputs that programmatically assign GitHub Copilot agents to issues or pull requests. This is distinct from the standard GitHub UI workflow for [assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) - this token is used for automated agent assignment through workflow safe outputs.
Primary token used by `assign-to-agent:` safe outputs to programmatically assign GitHub Copilot agents to issues or pull requests. This is distinct from the standard GitHub UI workflow for [assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) and is used specifically for automated agent assignment through workflow safe outputs.

**Required for**:

- `assign-to-agent:` safe outputs
- Programmatic agent assignment operations

**Token precedence and fallback**:

- If `GH_AW_AGENT_TOKEN` is set, it is always used for agent assignment.
- If `GH_AW_AGENT_TOKEN` is _not_ set, `gh-aw` falls back to `GH_AW_GITHUB_TOKEN`, and then to `GITHUB_TOKEN`, matching the runtime resolution `GH_AW_AGENT_TOKEN || GH_AW_GITHUB_TOKEN || GITHUB_TOKEN`.
Comment on lines +462 to +463
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new bullets describe GH_AW_AGENT_TOKEN as "always used" when set, but runtime precedence in getEffectiveAgentGitHubToken uses a custom/per-output token and top-level github-token before checking GH_AW_AGENT_TOKEN. This section should reflect the full precedence (custom/per-output → workflow-level → GH_AW_AGENT_TOKEN → GH_AW_GITHUB_TOKEN → GITHUB_TOKEN) or reword to avoid implying env var wins over explicitly configured tokens.

Suggested change
- If `GH_AW_AGENT_TOKEN` is set, it is always used for agent assignment.
- If `GH_AW_AGENT_TOKEN` is _not_ set, `gh-aw` falls back to `GH_AW_GITHUB_TOKEN`, and then to `GITHUB_TOKEN`, matching the runtime resolution `GH_AW_AGENT_TOKEN || GH_AW_GITHUB_TOKEN || GITHUB_TOKEN`.
- For agent assignment, `gh-aw` first uses any token explicitly configured for the safe output (for example, a custom/per-output token), then any workflow-level `github-token` input.
- If neither of those is provided and `GH_AW_AGENT_TOKEN` is set, it is used next for agent assignment.
- If `GH_AW_AGENT_TOKEN` is _not_ set, `gh-aw` falls back to `GH_AW_GITHUB_TOKEN`, and then to `GITHUB_TOKEN`, matching the runtime resolution: custom/per-output → workflow-level → `GH_AW_AGENT_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN`.

Copilot uses AI. Check for mistakes.

**Setup**:

The required token type and permissions depend on whether you own the repository or an organization owns it:
Expand Down Expand Up @@ -508,8 +513,6 @@ When an organization owns the repository, you need a fine-grained PAT with the r
gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT"
```

**Token precedence**: per-output → global safe-outputs → workflow-level → `GH_AW_AGENT_TOKEN` (no further fallback - must be explicitly configured)

> [!NOTE]
> Two ways to assign Copilot agents
>
Expand All @@ -534,7 +537,7 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT"
>
> Both methods result in the same outcome as [manually assigning issues to Copilot through the GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). Method 2 is simpler when creating issues, while method 1 provides fine-grained control for existing issues.
>
> **Technical Implementation**: Both methods use the GraphQL `replaceActorsForAssignable` mutation to assign the `copilot-swe-agent` bot to issues or PRs. The token precedence for both is: per-output → global safe-outputs → workflow-level → `GH_AW_AGENT_TOKEN` (with fallback to `GH_AW_GITHUB_TOKEN` or `GITHUB_TOKEN` if not set).
> **Technical Implementation**: Both methods use the GraphQL `replaceActorsForAssignable` mutation to assign the `copilot-swe-agent` bot to issues or PRs. Both follow the token precedence and fallback behavior documented above.
>
> See [GitHub's official documentation on assigning issues to Copilot](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more details on the Copilot coding agent.

Expand Down
Loading