Debugging GHE Cloud with Data Residency | GitHub Agentic Workflows
Skip to main content 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. Based on the debugging discussion in github/gh-aw#18480 . Prerequisites Section titled “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: Terminal window gh auth login --hostname yourorg.ghe.com Setup Section titled “Setup” These steps create a new workflow. For an existing failure, skip initialization and creation and continue with Troubleshooting . Step 1: Initialize Your Repository Section titled “Step 1: Initialize Your Repository” Terminal window GH_HOST = yourorg.ghe.com gh aw init Step 2: Add a Workflow Section titled “Step 2: Add a Workflow” Terminal window 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) Section titled “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 Section titled “Step 4: Compile” Terminal window 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 Section titled “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: Terminal window 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 Section titled “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: Terminal window 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 Section titled “Common Errors” “Authentication failed” Section titled ““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” Section titled ““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 Section titled ““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: Terminal window 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 Section titled “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 Section titled “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 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 Section titled “Advanced: Checking Firewall Logs” Download the workflow run artifacts and inspect sandbox/firewall/logs/access.log .
Each line shows wh
The rest of this page is on the live site.