GHES: Create prerequisites guide and troubleshooting runbook for Copilot engine

[lpcox]

Problem

There is no GHES-specific documentation for setting up agentic workflows with the Copilot engine. Users discover requirements through trial and error, facing hours of debugging for issues that have straightforward solutions.

Proposal: GHES Prerequisites Guide

Create documentation covering:

Prerequisites (site admin)

• GitHub Connect must be enabled (connects GHES to github.com for Copilot cloud services)
• Copilot licensing must be purchased and enabled at the enterprise level
• Network: Firewall must allow outbound to api.githubcopilot.com, api.enterprise.githubcopilot.com

Prerequisites (enterprise/org admin)

• Copilot seats must be assigned to the user whose PAT is used as COPILOT_GITHUB_TOKEN
• Token type: Fine-grained PAT with copilot_requests:read account permission (or classic PAT with copilot scope)
• Organization Copilot policy must allow the org to use Copilot

Workflow configuration

• engine.api-target must be set to api.<ghes-host>
• GHES domains must be added to firewall allowed domains
• GH_HOST must be configured for gh CLI commands

Proposal: Troubleshooting Runbook

Document known failure modes with solutions:

Symptom	Cause	Solution
Error loading models: 400 Bad Request	Copilot not licensed or API proxy routing wrong	Check enterprise Copilot settings; see gh-aw-firewall#1300
403 "unauthorized: not licensed to use Copilot"	No Copilot license/seat assigned	Site admin: enable Copilot; org admin: assign seat
403 "Resource not accessible by personal access token"	Wrong token type or missing permissions	Use fine-grained PAT with copilot_requests:read
Firewall blocks api.<ghes-host>:443	GHES domain not in allowed list	Add to engine.api-target or --allow-domains
Could not resolve to a Repository	GH_HOST not set	Add GHE configuration step to workflow
Wizard PR creation fails	Wizard targets github.com	Use gh aw add + manual gh pr create (see #20875)
gh aw audit fails	Same GH_HOST issue	GH_HOST=<ghes-host> gh aw audit <run-id>

Evidence

All of these issues were encountered and resolved during setup of agentic workflows on contoso-aw.ghe.com. Each required significant debugging time that documentation would have prevented.

Related

• add-wizard and add --create-pull-request fail to create PR on GitHub Enterprise Server repositories #20875, GHES: Add Copilot pre-flight diagnostic step before agent execution #20964, GHES: Wizard should auto-detect GHES and configure GH_HOST, api-target, and allowed domains #20965, GHES: gh aw audit should auto-detect GHES and set GH_HOST #20966, GHES: Replace opaque Copilot errors with actionable messages #20967 — All GHES-specific issues
• API proxy routes Copilot model requests to GHES API instead of Copilot API on Enterprise Server gh-aw-firewall#1300 — API proxy GHES routing