Skip to content

docs: add Copilot license/inference troubleshooting section #17242

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
pelikhan merged 2 commits into from
Feb 20, 2026
+30 −0
Merged

docs: add Copilot license/inference troubleshooting section #17242

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
bb8c639
Initial plan
Copilot Feb 20, 2026
0cf9a1a
Add Copilot license troubleshooting section and link from auth docs
Copilot Feb 20, 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
3 changes: 3 additions & 0 deletions docs/src/content/docs/reference/auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,9 @@ Then add the PAT to your GitHub Actions repository secrets as `COPILOT_GITHUB_TO
gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-github-pat>"
```

> [!TIP]
> 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](/gh-aw/troubleshooting/common-issues/#copilot-license-or-inference-access-issues) for a local diagnostic step.
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

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

The TIP suggests verifying the token owner has an active Copilot license, but inference failures at runtime can also be caused by exhausted premium-request quota. Consider mentioning quota as another common cause here (or wording this as “license/inference access and available quota”) to better match the linked troubleshooting section and user expectations.

Suggested change
> 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](/gh-aw/troubleshooting/common-issues/#copilot-license-or-inference-access-issues) for a local diagnostic step.
> 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 or inference access **and** that the account has sufficient remaining premium-request quota. See [Copilot License or Inference Access Issues](/gh-aw/troubleshooting/common-issues/#copilot-license-or-inference-access-issues) for a local diagnostic step.

Copilot uses AI. Check for mistakes.

<Video
src="/gh-aw/videos/create-pat-user-copilot.mp4"
caption="Creating a fine-grained PAT for user-owned repositories with Copilot permissions"
Expand Down
27 changes: 27 additions & 0 deletions docs/src/content/docs/troubleshooting/common-issues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,33 @@ Verify compilation succeeded. Compiled workflows include CLI installation steps.

Use default (`engine: copilot`) or specify available model (`engine: {id: copilot, model: gpt-4}`).

### Copilot License or Inference Access Issues

If your workflow fails during the Copilot inference step even though the `COPILOT_GITHUB_TOKEN` secret is configured correctly, the PAT owner's account may not have the necessary Copilot license or inference access.

**Symptoms**: The workflow fails with authentication or quota errors when the Copilot CLI tries to generate a response.

**Diagnosis**: Verify that the account associated with the `COPILOT_GITHUB_TOKEN` can successfully run inference by testing it locally.

1. Install the Copilot CLI locally by following the [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli).

2. Export the token as an environment variable:

```bash
export COPILOT_GITHUB_TOKEN="<your-github-pat>"
```

3. Run a simple inference test:

```bash
copilot -p "write a haiku"
Comment on lines +275 to +282
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

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

The local inference test uses copilot -p "write a haiku", but elsewhere in this repo the Copilot CLI is invoked with --prompt (see many workflow lockfiles). If -p isn’t a supported alias, this troubleshooting step will fail even for correctly licensed tokens; consider using the same copilot --prompt "…" form here.

Also, this file consistently uses fenced blocks like bash wrap; consider switching these new bash blocks to bash wrap for consistency and to avoid horizontal scrolling in the docs site.

Suggested change
```bash
export COPILOT_GITHUB_TOKEN="<your-github-pat>"
```
3. Run a simple inference test:
```bash
copilot -p "write a haiku"
```bash wrap
export COPILOT_GITHUB_TOKEN="<your-github-pat>"

  1. Run a simple inference test:

    copilot --prompt "write a haiku"

Copilot uses AI. Check for mistakes.
```

If this command fails, the account associated with the token does not have a valid Copilot license or inference access. Contact your organization administrator to verify that the token owner has an active Copilot subscription with inference enabled.

Comment on lines +267 to +286
Copy link

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

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

This section lists “quota errors” as a symptom, but the conclusion says failures mean the token owner “does not have a valid Copilot license or inference access.” Quota exhaustion (monthly premium requests) can also cause inference failures even with a valid license. Consider updating the diagnosis/conclusion to cover both cases (license/inference access vs. quota exceeded) and point to where users can check Copilot usage/billing.

Copilot uses AI. Check for mistakes.
> [!NOTE]
> The `COPILOT_GITHUB_TOKEN` must belong to a user account with an active GitHub Copilot subscription. Organization-managed Copilot licenses may have additional restrictions on programmatic API access.

## Context Expression Issues

### Unauthorized Expression
Expand Down