GHES: Replace opaque Copilot errors with actionable messages

[lpcox]

Problem

When the Copilot engine fails on GHES, error messages are opaque and do not indicate the root cause or how to fix it.

Actual root cause	Error users see
Copilot not licensed for enterprise/org	Error loading models: Error: Failed to list models: 400 Bad Request
Firewall blocks api.<ghes-host>:443	Firewall audit shows blocked domain, but no guidance
gh CLI not configured for GHES	Could not resolve to a Repository with the name 'owner/repo'
Wrong token type for Copilot	403 "Resource not accessible by personal access token" (no explanation of what token IS needed)

Proposal

Map known failure patterns to clear, actionable messages:

• 403 on /copilot_internal/v2/token → "Copilot token exchange failed (HTTP 403). 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. See: [GHES Copilot setup docs]"
• Firewall blocks GHES API domain → "GHES API domain api.<host> is not in the firewall allowed domains. Add it via engine.api-target in your workflow front matter."
• gh commands fail with resolution errors → "The gh CLI is targeting github.com instead of your GHES instance. Ensure GH_HOST is set to your GHES hostname."
• 400 on model loading → "Copilot model loading failed. On GHES, this may indicate the API proxy is routing requests to the wrong endpoint. See API proxy routes Copilot model requests to GHES API instead of Copilot API on Enterprise Server gh-aw-firewall#1300."

Evidence

On our GHES instance, we saw Error loading models: 400 Bad Request for hours before discovering (via manual diagnostics) that the actual error was 403 "unauthorized: not licensed to use Copilot". The 400 was a secondary error from the proxy, masking the real 403 from the token exchange.

Related

• API proxy routes Copilot model requests to GHES API instead of Copilot API on Enterprise Server gh-aw-firewall#1300 — API proxy routing issue on GHES