docs: add GHE Cloud data residency debugging guide

[lpcox]

Summary

Adds a comprehensive debugging guide for running agentic workflows on GHE Cloud with data residency (*.ghe.com).

Content sourced from the debugging discussion in #18480 (comment).

Changes

• New: docs/troubleshooting/debug-ghe.md — Step-by-step setup (init → add → configure api-target → compile → run) and troubleshooting (auth failures, GH_HOST issues, firewall logs, HTTP traffic capture, required domains reference)
• Updated: Cross-references added from:
  • troubleshooting/common-issues.md — GHES section tip box
  • reference/engines.md — api-target section link
  • setup/cli.md — GHES support section link

The troubleshooting sidebar is autogenerated, so the new page appears automatically.

Closes #18480

[Copilot]

Pull request overview

Adds a new troubleshooting guide for running Agentic Workflows on GitHub Enterprise Cloud (data residency, *.ghe.com) and links to it from existing setup/reference pages.

Changes:

• Added a new step-by-step “Debugging GHE Cloud with Data Residency” guide, including troubleshooting and advanced diagnostics.
• Linked the new guide from existing troubleshooting, CLI setup, and engine reference docs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
docs/src/content/docs/troubleshooting/debug-ghe.md	New end-to-end debugging/setup guide for GHEC data residency, including auth, api-target configuration, and network troubleshooting.
docs/src/content/docs/troubleshooting/common-issues.md	Adds a tip linking to the new GHEC data residency debugging guide.
docs/src/content/docs/setup/cli.md	Adds a link to the new GHEC data residency debugging guide from the CLI/GHES support section.
docs/src/content/docs/reference/engines.md	Adds a cross-reference to the new GHEC data residency debugging guide from the api-target docs.

Comments suppressed due to low confidence (1)

docs/src/content/docs/troubleshooting/debug-ghe.md:200

• In “Capturing HTTP Traffic” you note the Copilot CLI also contacts api.githubcopilot.com, but the “Required Domains Reference” table doesn’t mention it. If api.githubcopilot.com is required but already covered by defaults, add a row stating that (and that it’s auto-allowed via defaults) to avoid ambiguity when users are building strict allow-lists.

The traffic capture reveals the four domains the CLI uses 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 |

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This tip is under the “GitHub Enterprise Server Issues” section but links to a guide specifically about GitHub Enterprise Cloud data residency (*.ghe.com). That’s likely to confuse readers looking for GHES-only troubleshooting. Consider moving this link to a GHEC-specific section (or renaming the section to cover both GHES and GHEC) so the document structure matches the content.

[Copilot]

This runner diagnostic step sets GH_TOKEN: ${{ github.token }}. The built-in github.token/GITHUB_TOKEN typically won’t have Copilot entitlements, so this check may fail even when the COPILOT_GITHUB_TOKEN PAT is valid. Use the same auth mechanism as the workflow’s Execute step (e.g., COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}) or explicitly note that GH_TOKEN here must be a PAT with Copilot access.

This issue also appears on line 177 of the same file.

[lpcox]

@copilot open a new pull request to apply changes based on the comments in this thread

[Copilot]

@lpcox I've opened a new pull request, #21994, to work on those changes. Once the pull request is ready, I'll request review from you.