Suggest `permissions.copilot-requests: write` in agent failure issue when COPILOT_GITHUB_TOKEN is missing by Copilot · Pull Request #38722 · github/gh-aw

Copilot · 2026-06-11T20:49:45Z

When the Copilot engine's secret verification fails, the failure issue shows a generic "configure your secrets" message — missing a key alternative: org-level Copilot inference via permissions.copilot-requests: write, which requires no PAT at all.

Changes

handle_agent_failure.cjs: Extracts inline secret_verification_context ternary into buildSecretVerificationContext(secretVerificationResult, engineId). For Copilot, appends an additional paragraph pointing users to permissions.copilot-requests: write as a PAT-free alternative, presented as a fenced YAML code block with valid syntax; other engines keep the existing generic message. The Copilot branch now normalizes engineId case internally.
handle_agent_failure.test.cjs: Adds tests covering the no-failure (empty), non-copilot generic, and copilot-specific branches, including assertions for the Copilot-specific docs URL and mixed-case engineId handling.

Example of the added guidance for the copilot engine:

Alternative: If your organization has a Copilot subscription, you can avoid the need for a personal access token by adding a top-level permissions block to your workflow file. This enables Copilot inference through the org using the built-in GitHub Actions token.
permissions:
  copilot-requests: write

…gest permissions.copilot-requests:write Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

github-actions · 2026-06-11T22:40:15Z

✅ PR Code Quality Reviewer completed the code quality review.

github-actions · 2026-06-11T22:40:17Z

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #38722 does not have the implementation label (has_implementation_label=false) and has 0 new lines of code in business logic directories (≤100 threshold, requires_adr_by_default_volume=false).

github-actions

Clean refactor that correctly extracts duplicated inline string-building into a named, testable function. No blocking bugs found. Four non-blocking issues noted inline.

### Summary of findings

Medium

engineId comparison at line 1889 does not normalize to lowercase internally; the function is now exported and any future caller skipping .toLowerCase() will silently miss the Copilot suggestion.
User-facing copy at line 1891 says "workflow frontmatter" — not a GitHub Actions concept; users searching the docs for this term will find nothing.

Low

Copilot test is missing an assertion for the #github-copilot-default URL, the only output line unique to the Copilot branch.
Test description uses permissions.copilot-requests:write (dot notation, no space) rather than the actual YAML form copilot-requests: write.

🔎 Code quality review by PR Code Quality Reviewer · 400.8 AIC · ⌖ 13.3 AIC

github-actions · 2026-06-11T22:52:04Z

+    buildWarningAlertLine("Secret Verification Failed", "The workflow's secret validation step failed. Please check that the required secrets are configured in your repository settings.") +
+    "\nFor more information on configuring tokens, see: https://github.github.com/gh-aw/reference/engines/\n";
+
+  if (engineId === "copilot") {


engineId comparison is not normalized — callers passing mixed-case will silently miss the Copilot suggestion. The function is now exported and reusable, but it places the burden on every caller to pre-lowercase the value.

💡 Suggested fix

Add a single normalization inside the function instead of relying on caller discipline:

if ((engineId || "").toLowerCase() === "copilot") {

The two existing call sites in main() already pass a lowercased engineId (line 2572), so this is safe and backward-compatible. But as soon as a third call site is added — or a test passes "Copilot" — the Copilot-specific block will be silently skipped with no error or warning, and users will see only the generic secret-verification message.

github-actions · 2026-06-11T22:52:04Z

+
+  if (engineId === "copilot") {
+    context +=
+      "\n**Alternative**: If your organization has a Copilot subscription, you can avoid the need for a personal access token by adding the following to your workflow frontmatter. This enables Copilot inference through the org using the built-in GitHub Actions token.\n" +


"workflow frontmatter" is not a GitHub Actions concept and will confuse users. Frontmatter is a static-site-generator term (YAML delimited by --- in Markdown files). GitHub Actions workflows have no such element, so users who search the docs for this term will find nothing.

💡 Suggested fix

Replace:

adding the following to your workflow frontmatter

With something like:

adding a top-level `permissions` block to your workflow file

For example:

This enables Copilot inference through the org using the built-in GitHub Actions token by adding a top-level `permissions` block to your workflow file.

This matches the language used in GitHub Actions documentation and helps users find the right place to make the change.

github-actions · 2026-06-11T22:52:04Z

+      const result = buildSecretVerificationContext("failed", "copilot");
+      expect(result).toContain("Secret Verification Failed");
+      expect(result).toContain("required secrets are configured");
+      expect(result).toContain("```yaml\npermissions:\n  copilot-requests: write\n```");


The Copilot-specific reference URL is untested — if it were accidentally removed, all tests would still pass. The implementation appends a See: https://github.github.com/gh-aw/reference/engines/#github-copilot-default line that is unique to the Copilot branch, but no assertion checks for it.

💡 Suggested addition

expect(result).toContain("https://github.github.com/gh-aw/reference/engines/#github-copilot-default");

The generic URL (/engines/) is already covered by the claude test above; the Copilot-specific anchor (#github-copilot-default) is not. Adding this closes the coverage gap and locks in the exact link that users are expected to follow.

github-actions · 2026-06-11T22:52:04Z

+      expect(result).not.toContain("copilot-requests");
+    });
+
+    it("returns copilot-specific message with permissions.copilot-requests:write suggestion when verification failed", () => {


Test description notation does not match the YAML it describes. permissions.copilot-requests:write (dot-delimited, no space after colon) is not valid YAML syntax; the actual permission key-value pair emitted is copilot-requests: write (colon + space). The mismatch is visible in every CI run and misleads whoever reads the test output.

💡 Suggested fix

Change:

"returns copilot-specific message with permissions.copilot-requests:write suggestion when verification failed"

To:

"returns copilot-specific message with copilot-requests: write permissions suggestion when verification failed"

pelikhan · 2026-06-11T22:58:37Z

@copilot run pr-finisher skill

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-06-11T23:15:56Z

@copilot run pr-finisher skill

Ran pr-finisher pass and pushed follow-up fixes in 33bfd58.

Normalized engineId handling in buildSecretVerificationContext to handle mixed case.
Reworded guidance to reference a top-level permissions block in the workflow file.
Strengthened tests (Copilot reference URL assertion + mixed-case engine-id coverage + corrected test title wording).

Local validation passed: make fmt, make lint, make test-unit, make test, make recompile.

CI on this new HEAD is still unverified until a maintainer re-triggers workflows.

Customize agent failure issue for missing COPILOT_GITHUB_TOKEN to sug…

4951fda

…gest permissions.copilot-requests:write Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI assigned Copilot and pelikhan Jun 11, 2026

Copilot AI changed the title ~~Customize agent failure issue for missing COPILOT_GITHUB_TOKEN to suggest permissions.copilot-requests:write~~ Suggest permissions.copilot-requests:write in agent failure issue when COPILOT_GITHUB_TOKEN is missing Jun 11, 2026

Copilot created this pull request from a session on behalf of pelikhan June 11, 2026 20:50 View session

Copilot finished work on behalf of pelikhan June 11, 2026 20:50

Copilot AI requested a review from pelikhan June 11, 2026 20:50

pelikhan reviewed Jun 11, 2026

View reviewed changes

Comment thread actions/setup/js/handle_agent_failure.cjs Outdated

Copilot started work on behalf of pelikhan June 11, 2026 20:51 View session

Use fenced YAML code block for copilot-requests permission snippet

1dd58de

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan June 11, 2026 21:02

Copilot AI requested a review from pelikhan June 11, 2026 21:02

Merge branch 'main' into copilot/customize-agent-failure-issue

9b32bd9

pelikhan marked this pull request as ready for review June 11, 2026 22:33

Copilot AI review requested due to automatic review settings June 11, 2026 22:33

Copilot started reviewing on behalf of pelikhan June 11, 2026 22:34 View session

Copilot AI reviewed Jun 11, 2026

github-actions Bot mentioned this pull request Jun 11, 2026

[aw] No-Op Runs #38697

Closed

github-actions Bot reviewed Jun 11, 2026

View reviewed changes

Merge branch 'main' into copilot/customize-agent-failure-issue

eb12d13

Copilot started work on behalf of pelikhan June 11, 2026 22:59 View session

Address PR review feedback on copilot secret guidance

33bfd58

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~Suggest permissions.copilot-requests:write in agent failure issue when COPILOT_GITHUB_TOKEN is missing~~ Suggest permissions.copilot-requests: write in agent failure issue when COPILOT_GITHUB_TOKEN is missing Jun 11, 2026

Copilot finished work on behalf of pelikhan June 11, 2026 23:16

pelikhan merged commit 32fdaea into main Jun 11, 2026
15 checks passed

pelikhan deleted the copilot/customize-agent-failure-issue branch June 11, 2026 23:18

This was referenced Jun 12, 2026

Smoke Test: Claude - 27385890715 #38750

Closed

[docs] Update documentation for features from 2026-06-12 #38828

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Suggest `permissions.copilot-requests: write` in agent failure issue when COPILOT_GITHUB_TOKEN is missing#38722

Suggest `permissions.copilot-requests: write` in agent failure issue when COPILOT_GITHUB_TOKEN is missing#38722
pelikhan merged 5 commits into
mainfrom
copilot/customize-agent-failure-issue

Copilot AI commented Jun 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

github-actions Bot Jun 11, 2026

Uh oh!

github-actions Bot Jun 11, 2026

Uh oh!

github-actions Bot Jun 11, 2026

Uh oh!

github-actions Bot Jun 11, 2026

Uh oh!

pelikhan commented Jun 11, 2026

Uh oh!

Copilot AI commented Jun 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

pelikhan commented Jun 11, 2026

Uh oh!

Copilot AI commented Jun 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jun 11, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading