From c83d667629b9386915c4e48df906209253d90ecd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 18 Mar 2026 04:26:22 +0000 Subject: [PATCH] docs: update GHES CLI docs and add Copilot GHES troubleshooting guide - cli.md: document that custom frontmatter jobs and safe-outputs now automatically have GH_HOST configured (from PR #21523). Remove the instruction to manually source configure_gh_for_ghe.sh for GH_HOST. Note that when GH_TOKEN is set the script skips gh auth login (PR #21525). - common-issues.md: add "GitHub Enterprise Server Issues" section with Copilot prerequisites checklist (GitHub Connect, licensing, seats, token type) and a troubleshooting table for common GHES error messages (400 Bad Request, 403 not licensed, 403 PAT, Could not resolve Repository, firewall blocks, wizard PR on wrong host). Closes #20968 Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/setup/cli.md | 6 +- .../docs/troubleshooting/common-issues.md | 72 +++++++++++++++++++ 2 files changed, 76 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 27c2081a2c9..734b194bfad 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -83,7 +83,9 @@ Commands that support `--create-pull-request` (such as `gh aw add`, `gh aw add-w The compiled agent job automatically runs `configure_gh_for_ghe.sh` before the agent starts executing. The script detects the GitHub host from the `GITHUB_SERVER_URL` environment variable (set by GitHub Actions on GHES) and configures `gh` to authenticate against it. No configuration is required for the agent to use `gh` CLI commands on your GHES instance. -For custom `steps:` that run outside the agent sandbox (for example, pre-agent data gathering or post-agent reporting), source the helper script manually: +Custom workflow jobs (independent GitHub Actions jobs defined in workflow frontmatter) and the safe-outputs job automatically have `GH_HOST` derived from `GITHUB_SERVER_URL` at the start of each job. On github.com this is a no-op; on GHES/GHEC it ensures all `gh` CLI commands in the job target the correct instance without any manual setup. + +For custom `steps:` that require additional authentication setup (for example, when running `gh` commands without a `GH_TOKEN` in scope), the helper script is available: ```yaml wrap steps: @@ -98,7 +100,7 @@ steps: gh pr list --state open --limit 200 --json number,title ``` -The script is installed to `/opt/gh-aw/actions/configure_gh_for_ghe.sh` by the setup action. +The script is installed to `/opt/gh-aw/actions/configure_gh_for_ghe.sh` by the setup action. When `GH_TOKEN` is already set in the environment, the script skips `gh auth login` and only exports `GH_HOST` — the token handles authentication. > [!NOTE] > Custom steps run outside the agent firewall sandbox and have access to standard GitHub Actions environment variables including `GITHUB_SERVER_URL`, `GITHUB_TOKEN`, and `GH_TOKEN`. diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md index 6d590ab663f..3b4ba07ccc1 100644 --- a/docs/src/content/docs/troubleshooting/common-issues.md +++ b/docs/src/content/docs/troubleshooting/common-issues.md @@ -305,6 +305,78 @@ If this command fails, the account associated with the token does not have a val > [!NOTE] > The `COPILOT_GITHUB_TOKEN` must belong to a user account with an active GitHub Copilot subscription. Organization-managed Copilot licenses may have additional restrictions on programmatic API access. +## GitHub Enterprise Server Issues + +### Copilot Engine Prerequisites on GHES + +Before running Copilot-based workflows on GHES, verify the following: + +**Site admin requirements:** +- **GitHub Connect** must be enabled — it connects GHES to github.com for Copilot cloud services. +- **Copilot licensing** must be purchased and activated at the enterprise level. +- The firewall must allow outbound HTTPS to `api.githubcopilot.com` and `api.enterprise.githubcopilot.com`. + +**Enterprise/org admin requirements:** +- Copilot seats must be assigned to the user whose PAT is used as `COPILOT_GITHUB_TOKEN`. +- The organization's Copilot policy must allow Copilot usage. + +**Workflow configuration:** + +```aw wrap +engine: + id: copilot + api-target: api.enterprise.githubcopilot.com +network: + allowed: + - defaults + - api.enterprise.githubcopilot.com +``` + +See [Enterprise API Endpoint](/gh-aw/reference/engines/#enterprise-api-endpoint-api-target) for GHEC/GHES `api-target` values. + +### Copilot GHES: Common Error Messages + +**`Error loading models: 400 Bad Request`** + +Copilot is not licensed at the enterprise level or the API proxy is routing incorrectly. Verify enterprise Copilot settings and confirm GitHub Connect is enabled. + +**`403 "unauthorized: not licensed to use Copilot"`** + +No Copilot license or seat is assigned to the PAT owner. Contact the site admin to enable Copilot at the enterprise level, then have an org admin assign a seat to the token owner. + +**`403 "Resource not accessible by personal access token"`** + +Wrong token type or missing permissions. Use a fine-grained PAT with the **Copilot Requests: Read** account permission, or a classic PAT with the `copilot` scope. See [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) for setup instructions. + +**`Could not resolve to a Repository`** + +`GH_HOST` is not set when running `gh` commands. This typically occurs in custom frontmatter jobs from older compiled workflows. Recompile with `gh aw compile` — compiled workflows now automatically export `GH_HOST` in custom jobs. + +For local CLI commands (`gh aw audit`, `gh aw add-wizard`), ensure you are inside a GHES repository clone or set `GH_HOST` explicitly: + +```bash wrap +GH_HOST=github.company.com gh aw audit +``` + +**Firewall blocks outbound HTTPS to `api.`** + +Add the GHES domain to your workflow's allowed list: + +```aw wrap +engine: + id: copilot + api-target: api.company.ghe.com +network: + allowed: + - defaults + - company.ghe.com + - api.company.ghe.com +``` + +**`gh aw add-wizard` or `gh aw init` creates a PR on github.com instead of GHES** + +Run these commands from inside a GHES repository clone — they auto-detect the GHES host from the git remote. If PR creation still fails, use `gh aw add` to generate the workflow file, then create the PR manually with `gh pr create`. + ## Context Expression Issues ### Unauthorized Expression