Debugging GHE Cloud with Data Residency

This guide walks you through setting up and running agentic workflows on GitHub Enterprise Cloud with data residency (*.ghe.com). It reflects the configuration needed as of gh aw v0.61.1+ for enterprises using data residency in the EU or other regions.

For an existing failed run, start with the debugging bootstrap and shared debugging strategy, using the full https://yourorg.ghe.com/OWNER/REPO/actions/runs/RUN_ID URL. Those instructions own setup, evidence collection, review, and live-execution gates; this page adds enterprise-specific configuration, not a separate debug loop. The v0.61.1 references describe historical support, not a recommended current version.

Tip

The one thing you must do differently from github.com is set api-target in your workflow frontmatter to copilot-api.<yourorg>.ghe.com. Everything else flows from that.

Based on the debugging discussion in github/gh-aw#18480.

Prerequisites

For new-repository setup, use a supported gh aw version following the bootstrap’s CLI checks. You need a repository on your GHE Cloud data residency instance (for example, yourorg.ghe.com), Copilot enabled for your enterprise, and gh authenticated against your GHE host:

gh auth login --hostname yourorg.ghe.com

Setup

These steps create a new workflow. For an existing failure, skip initialization and creation and continue with Troubleshooting.

Step 1: Initialize Your Repository

GH_HOST=yourorg.ghe.com gh aw init

Step 2: Add a Workflow

GH_HOST=yourorg.ghe.com gh aw add-wizard githubnext/agentics/repo-assist

Follow the prompts to configure the workflow for your repository.

Step 3: Configure the Engine for GHE (Critical)

Open the generated workflow .md file (e.g., .github/workflows/repo-assist.md) and ensure the engine section in the YAML frontmatter includes api-target pointing to your enterprise’s Copilot API subdomain:

engine:
  id: "copilot"
  api-target: "copilot-api.yourorg.ghe.com"

Replace yourorg with your enterprise’s slug — the subdomain portion of yourorg.ghe.com.

Why this is required: On GHE Cloud with data residency, Copilot inference runs on a dedicated subdomain (copilot-api.yourorg.ghe.com) rather than the default api.githubcopilot.com. Without api-target, the AWF api-proxy routes requests to the wrong host, resulting in authentication failures.

See Enterprise API Endpoint for full api-target documentation.

Step 4: Compile

GH_HOST=yourorg.ghe.com gh aw compile repo-assist

The compiler (v0.61.1+) automatically adds your GHE domains (api.yourorg.ghe.com, copilot-api.yourorg.ghe.com) to the firewall allow-list, sets --copilot-api-target for the AWF api-proxy, and configures GH_HOST so the gh CLI targets the correct host.

Step 5: Publish and Test Within the Shared Gates

Follow the shared branch-testing path. For debugging, first use gh aw compile repo-assist --dry-run under the compilation guide. Review the resulting source and diagnostic lock together before any permitted live dry-run test, then publish that exact pair to the authorized feature branch. The dispatch command selects a ref; it does not enable dry-run protections:

GH_HOST=yourorg.ghe.com gh aw run repo-assist --ref REVIEWED_BRANCH

Compilation alone does not authorize execution. A general debugging request does not authorize this command, and explicit no-dispatch rules take precedence.

Troubleshooting

Use your existing coding-agent session and the shared debugging route; a local Copilot CLI is optional assistant setup, not a required diagnostic or a test of the workflow’s engine. Only if starting a new local assistant, check host authentication metadata and launch Copilot:

GH_HOST=yourorg.ghe.com gh auth status
GH_HOST=yourorg.ghe.com copilot

Invoke the agentic-workflows skill and provide the existing failed run, for example:

Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md

Run URL: https://yourorg.ghe.com/OWNER/REPO/actions/runs/RUN_ID

Copilot can inspect your workflow files, existing run logs, and gh aw audit output without dispatching another run. Never send enterprise credentials to the public raw-content host used for gh-aw guidance.

Common Errors

“Authentication failed”

Error: Authentication failed
Your GitHub token may be invalid, expired, or lacking the required permissions.

Possible cause: A missing or incorrect api-target routes inference to the wrong endpoint. Compare the failed revision and existing api-proxy/authentication logs before attributing the error; token-source and permission failures can produce similar symptoms.

Fix when confirmed: Verify your .md frontmatter has:

engine:
  id: "copilot"
  api-target: "copilot-api.yourorg.ghe.com"

Test the source change first with GH_HOST=yourorg.ghe.com gh aw compile WORKFLOW --dry-run under the shared compilation and review gates.

“none of the git remotes point to a known GitHub host”

Cause: GH_HOST is not set. The gh CLI doesn’t recognize your GHE instance as a GitHub host.

Fix: Use the supplied enterprise host for CLI evidence reads and inspect the failed revision’s generated GH_HOST configuration. Follow the bootstrap’s version checks; do not upgrade an intentional pin based on this symptom alone.

“Not Found” during checkout steps

Cause: The lock file is trying to access github.com repositories with your GHE-scoped token. This can happen with local builds of the compiler that use actions/checkout instead of the published github/gh-aw-actions action reference.

Fix when confirmed: Inspect the checkout action reference in the failed lock and compiler provenance. Test the source with a trusted installed compiler rather than executing an unreviewed local build:

GH_HOST=yourorg.ghe.com gh aw compile <workflow-name> --dry-run

See also Copilot GHES: Common Error Messages for additional error patterns.

Advanced: Testing Copilot on the Runner Directly

First compare existing installation, authentication, firewall, and api-proxy logs to identify the failing boundary. Do not hand-edit generated locks or run Copilot outside AWF to bypass isolation. If component reproduction is necessary, use the shared strategy’s reviewed, isolated test bindings and fixtures; leave hosted credentials and runner behavior unverified until an authorized live test.

Advanced: Capturing HTTP Traffic

Prefer existing firewall and api-proxy artifacts. If additional HTTP diagnostics are necessary, review a separate diagnostic source change under the shared strategy before executing or publishing it. Do not hand-edit the Execute step. Copilot’s Node.js runtime supports these diagnostic environment variables:

env:
  NODE_DEBUG: fetch,undici
  UNDICI_DEBUG: full

Caution

The Copilot CLI uses Node.js fetch()/undici internally, not the built-in http/https modules. Setting NODE_DEBUG=http,https will capture nothing. You must use UNDICI_DEBUG=full.

Treat captured headers, bodies, and authorization URLs as sensitive; keep raw captures private and redact before reuse. Traffic may include these domains on data residency:

Domain	Purpose
api.yourorg.ghe.com	REST API, Copilot auth (/copilot_internal/user)
copilot-api.yourorg.ghe.com	Inference, model listing, MCP
copilot-telemetry-service.yourorg.ghe.com	Telemetry
api.githubcopilot.com	Shared Copilot services

Advanced: Checking Firewall Logs

Download the workflow run artifacts and inspect sandbox/firewall/logs/access.log. Each line shows whether a domain was allowed (TCP_TUNNEL) or blocked (DENIED). Verify that your yourorg.ghe.com domains appear as TCP_TUNNEL.

Required Domains Reference

For GHE Cloud with data residency, the following domains must be reachable from inside the AWF sandbox. The compiler adds most of these automatically when api-target is set:

Domain	Auto-added by compiler?	Required for
yourorg.ghe.com	✓	Git, web UI
api.yourorg.ghe.com	✓	REST API, Copilot auth
copilot-api.yourorg.ghe.com	✓	Inference, models, MCP
copilot-telemetry-service.yourorg.ghe.com	✗ (add manually if needed)	Telemetry

To add the telemetry domain manually:

network:
  allowed:
    - defaults
    - copilot-telemetry-service.yourorg.ghe.com