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
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)
api.githubcopilot.com,api.enterprise.githubcopilot.comPrerequisites (enterprise/org admin)
COPILOT_GITHUB_TOKENcopilot_requests:readaccount permission (or classic PAT withcopilotscope)Workflow configuration
engine.api-targetmust be set toapi.<ghes-host>GH_HOSTmust be configured forghCLI commandsProposal: Troubleshooting Runbook
Document known failure modes with solutions:
Error loading models: 400 Bad Request403 "unauthorized: not licensed to use Copilot"403 "Resource not accessible by personal access token"copilot_requests:readapi.<ghes-host>:443engine.api-targetor--allow-domainsCould not resolve to a RepositoryGH_HOSTnot setgh aw add+ manualgh pr create(see #20875)gh aw auditfailsGH_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