GHES: Replace opaque Copilot errors with actionable messages

[Claude]

Summary

This PR adds comprehensive GHES-specific error detection for the Copilot engine, replacing opaque error messages with clear, actionable guidance for common GHES deployment issues.

Changes

Detection Script

• Added detect_ghes_copilot_errors.sh to detect 4 common GHES error patterns:
  • 403 on token exchange - Copilot not licensed or GitHub Connect issues
  • 400 on model loading - API proxy routing problems
  • Firewall blocks - GHES API domain not in allowed domains
  • gh CLI misconfiguration - CLI targeting github.com instead of GHES

Error Message Templates

• Created actionable error message templates for each error type:
  • ghes_token_exchange_error.md - Licensing and GitHub Connect resolution steps
  • ghes_model_loading_error.md - API proxy troubleshooting
  • ghes_firewall_block_error.md - Firewall configuration guidance
  • ghes_gh_cli_error.md - gh CLI configuration fixes

Compiler Integration

• Added GHES error detection step to Copilot engine workflows (runs after agent execution)
• Added 4 new job outputs for GHES errors (ghes_token_exchange_403, ghes_model_loading_400, ghes_firewall_block, ghes_gh_cli_misconfigured)
• Pass GHES error outputs to conclusion job for error reporting
• Updated failure message templates to include GHES error context

Tests

• Added comprehensive tests in ghes_copilot_errors_test.go:
  • Verifies GHES error detection step is generated for Copilot workflows
  • Verifies error outputs are exposed in agent job
  • Verifies error environment variables are passed to conclusion job
  • Verifies non-Copilot engines don't include GHES error detection
• Updated golden test files for workflow compilation

Testing

All tests pass:

• ✅ GHES error detection tests
• ✅ Golden file tests (updated for new outputs)
• ✅ Build and formatting validation

Example Error Messages

When a GHES-specific error is detected, users will see actionable guidance like:

Token Exchange 403:

🔑 Copilot Token Exchange Failed (GHES): The Copilot CLI received a 403 error when attempting to exchange your GitHub token for a Copilot access token. This usually means Copilot is not licensed for this enterprise or organization. Ask your GHES site admin to: 1) Enable GitHub Connect, 2) Enable Copilot at the enterprise level, 3) Assign a Copilot seat to the token owner.

Model Loading 400:

⚠️ Copilot Model Loading Failed (GHES): The Copilot CLI received a 400 error when attempting to load available models. On GHES, this often indicates an API proxy routing issue.

Firewall Block:

🔥 GHES API Domain Blocked by Firewall: The workflow firewall is blocking access to your GHES API domain, preventing the Copilot CLI from communicating with the server.

gh CLI Misconfiguration:

🔧 gh CLI Misconfigured for GHES: The gh CLI is targeting github.com instead of your GHES instance, causing repository resolution errors.

[lpcox]

@claude[agent] fix the pr title and summary

[Claude]

@claude[agent] fix the pr title and summary

Updated PR title to "GHES: Replace opaque Copilot errors with actionable messages" and added comprehensive description with implementation details, testing information, and example error messages. (8a960c1)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/graphql
  • Triggering command: /usr/bin/gh gh pr view --json title,body /home/REDACTED/.nvm/bash_completion /home/REDACTED/.nvm/install.sh /home/REDACTED/.nvm/nvm-exec /home/REDACTED/.nvm/nvm.sh /home/REDACTED/.nvm/package.json /home/REDACTED/.nvm/rename_test.sh /home/REDACTED/.nvm/test (http block)
  • Triggering command: /usr/bin/gh gh pr list --head claude/replace-opaque-copilot-errors --json number,title,body --limit 1 /home/REDACTED/.nvm/package.json /home/REDACTED/.nvm/rename_test.sh /home/REDACTED/.nvm/test (http block)
  • Triggering command: `/usr/bin/gh gh pr edit --title GHES: Replace opaque Copilot errors with actionable messages --body ## Summary

This PR adds comprehensive GHES-specific error detection for the Copilot engine, replacing opaque error messages with clear, actionable guidance for common GHES deployment issues.

Changes

Detection Script

• Added detect_ghes_copilot_ /home/REDACTED/.nvm/nvm-exec /home/REDACTED/.nvm/nvm.sh /home/REDACTED/.nvm/package.json /home/REDACTED/.nvm/rename_test.sh /home/REDACTED/.nvm/test (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)