anthropics · MukundaKatta · Apr 26, 2026
diff --git a/README.md b/README.md
@@ -31,6 +31,7 @@ This command will guide you through setting up the GitHub app and required secre
 
 - You must be a repository admin to install the GitHub app and add secrets
 - This quickstart method is only available for direct Anthropic API users. For AWS Bedrock, Google Vertex AI, or Microsoft Foundry setup, see [docs/cloud-providers.md](./docs/cloud-providers.md).
+- Using **GitHub Enterprise Cloud**? See [docs/github-enterprise-cloud.md](./docs/github-enterprise-cloud.md) for GHEC-specific setup (data residency, EMU, SSO, IP allowlists).
 
 ## 📚 Solutions & Use Cases
 
@@ -53,6 +54,7 @@ Each solution includes complete working examples, configuration details, and exp
 - **[Solutions Guide](./docs/solutions.md)** - **🎯 Ready-to-use automation patterns**
 - **[Migration Guide](./docs/migration-guide.md)** - **⭐ Upgrading from v0.x to v1.0**
 - [Setup Guide](./docs/setup.md) - Manual setup, custom GitHub apps, and security best practices
+- [GitHub Enterprise Cloud](./docs/github-enterprise-cloud.md) - GHEC setup (standard and data residency)
 - [Usage Guide](./docs/usage.md) - Basic usage, workflow configuration, and input parameters
 - [Custom Automations](./docs/custom-automations.md) - Examples of automated workflows and custom prompts
 - [Configuration](./docs/configuration.md) - MCP servers, permissions, environment variables, and advanced settings

diff --git a/docs/github-enterprise-cloud.md b/docs/github-enterprise-cloud.md
@@ -0,0 +1,137 @@
+# GitHub Enterprise Cloud (GHEC) Setup
+
+This guide covers setup specific to **GitHub Enterprise Cloud (GHEC)**. If you're on `github.com` (personal or organization accounts on the standard plan), follow the [main Setup Guide](./setup.md) instead.
+
+GHEC has two flavors with different rules for installing GitHub Apps:
+
+| Flavor | Hostname | Marketplace `claude` app | Custom GitHub App |
+|---|---|---|---|
+| Standard GHEC (no data residency) | `github.com` / `api.github.com` | Supported | Supported |
+| GHEC with data residency | `SUBDOMAIN.ghe.com` / `api.SUBDOMAIN.ghe.com` | Not available | Required |
+
+> **Quick check:** if your organization URL looks like `https://github.com/your-org`, you're on standard GHEC. If it looks like `https://your-org.ghe.com`, you're on GHEC with data residency.
+
+## Standard GHEC (github.com)
+
+Standard GHEC orgs share infrastructure with `github.com`, so the marketplace [Claude app](https://github.com/apps/claude) and the [main Setup Guide](./setup.md) apply. The differences are organizational:
+
+### 1. Confirm third-party access policy
+
+Many GHEC orgs restrict third-party application access. Owners can check at:
+
+```
+https://github.com/organizations/YOUR-ORG/settings/oauth_application_policy
+```
+
+If "Third-party application access policy" is set to **restricted**, an org owner needs to approve the Claude GitHub App after a member requests installation.
+
+### 2. Enterprise Managed Users (EMU)
+
+If your enterprise uses [Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users), the marketplace Claude app **cannot be installed** into EMU organizations. Use the [Custom GitHub App path](./setup.md#using-a-custom-github-app) instead, created inside the EMU enterprise.
+
+### 3. SAML SSO authorization
+
+If your org enforces SAML single sign-on, any Personal Access Token, OAuth token, or App installation token used by the workflow must be **SSO-authorized** for the org. For PATs, click "Configure SSO" on the token at `https://github.com/settings/tokens` and authorize it for the target org. App installation tokens generated by `actions/create-github-app-token` are automatically scoped to the install and don't need separate SSO authorization.
+
+### 4. IP allowlists
+
+If your org has an [IP allowlist](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/managing-allowed-ip-addresses-for-organizations-in-your-enterprise/managing-allowed-ip-addresses-for-your-organization), self-hosted runners must originate from an allowlisted IP, **and** GitHub-hosted runners' egress addresses must be allowed. Enable "Allow GitHub Actions to access" in the IP allowlist settings, otherwise runner-to-`api.github.com` calls succeed but installation token issuance and other GitHub App operations may fail.
+
+After confirming the above, follow the [main Setup Guide](./setup.md). Workflow files don't need any GHEC-specific changes.
+
+## GHEC with Data Residency (`*.ghe.com`)
+
+GHEC with data residency is a separate tenant with its own hostname (for example `your-company.ghe.com`) and its own API endpoint (`api.your-company.ghe.com`). The marketplace `claude` app lives on `github.com` and is **not installable** into a `.ghe.com` enterprise.
+
+You must create a custom GitHub App **inside your `.ghe.com` enterprise**, then run the action from that enterprise's runners.
+
+### How the action picks up the right endpoint
+
+The action reads `GITHUB_API_URL` and `GITHUB_SERVER_URL` from the runner environment. GitHub Actions runners attached to a `.ghe.com` enterprise set these automatically:
+
+- `GITHUB_SERVER_URL=https://your-company.ghe.com`
+- `GITHUB_API_URL=https://api.your-company.ghe.com`
+
+You don't need to override these in your workflow. (Source: [`src/github/api/config.ts`](../src/github/api/config.ts) -- both fall back to `github.com` only if unset.)
+
+If you're invoking the action from a runner that doesn't auto-set these (rare), set them explicitly:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  env:
+    GITHUB_API_URL: https://api.your-company.ghe.com
+    GITHUB_SERVER_URL: https://your-company.ghe.com
+  with:
+    # ... other inputs
+```
+
+### Setup steps
+
+1. **Create a custom GitHub App in your data-residency tenant:**
+   - Go to `https://your-company.ghe.com/organizations/YOUR-ORG/settings/apps/new` (org-level) or your enterprise app settings.
+   - You can paste the manifest from [`github-app-manifest.json`](../github-app-manifest.json) into the "Create from manifest" flow, or configure manually with these minimum **repository permissions**:
+     - Contents: Read & Write
+     - Issues: Read & Write
+     - Pull requests: Read & Write
+   - For automation that reads CI status, also grant Actions: Read.
+
+2. **Generate a private key** for the app and download the `.pem`.
+
+3. **Install the app** on the repos where you want Claude to operate.
+
+4. **Add secrets** to each repository (Settings -> Secrets and variables -> Actions):
+   - `APP_ID` -> the custom app's ID
+   - `APP_PRIVATE_KEY` -> the contents of the `.pem` file
+   - One of: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, or cloud-provider credentials (see [Cloud Providers](./cloud-providers.md))
+
+5. **Use the custom-app token in your workflow**, the same way as in the [Custom GitHub App](./setup.md#using-a-custom-github-app) section:
+
+   ```yaml
+   jobs:
+     claude:
+       runs-on: ubuntu-latest
+       permissions:
+         contents: write
+         issues: write
+         pull-requests: write
+         id-token: write
+       steps:
+         - name: Generate GitHub App token
+           id: app-token
+           uses: actions/create-github-app-token@v2
+           with:
+             app-id: ${{ secrets.APP_ID }}
+             private-key: ${{ secrets.APP_PRIVATE_KEY }}
+             # github-api-url is auto-detected from GITHUB_API_URL on data-residency runners
+
+         - uses: anthropics/claude-code-action@v1
+           with:
+             anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+             github_token: ${{ steps.app-token.outputs.token }}
+   ```
+
+### Air-gapped / private network egress
+
+If your data-residency tenant restricts outbound network access:
+
+- The action makes Anthropic API calls (`api.anthropic.com`) from the runner. Allowlist that host on the runner's network, **or** route through AWS Bedrock / Google Vertex AI / Microsoft Foundry per [Cloud Providers](./cloud-providers.md) so model traffic stays in your cloud account.
+- The action pulls a pinned `ghcr.io/github/github-mcp-server` image when GitHub MCP tools are enabled (see [`src/mcp/install-mcp-server.ts`](../src/mcp/install-mcp-server.ts)). Allowlist `ghcr.io` on the runner or pre-pull the image into a private registry.
+- Bun is downloaded by the action's setup step. Pre-install it on self-hosted runners and pass `path_to_bun_executable` (see [FAQ](./faq.md#how-can-i-use-custom-executables-in-specialized-environments)) if `https://bun.sh` is blocked.
+
+## Common Gotchas
+
+- **`403 Resource not accessible by integration` from `/user`** -- previously a known issue on Enterprise instances ([#520](https://github.com/anthropics/claude-code-action/issues/520)). Fixed by the `bot_id` / `bot_name` defaults; see the [FAQ entry](./faq.md#why-am-i-getting-403-resource-not-accessible-by-integration-errors).
+- **Workflow runs but no comment appears** -- check that the GitHub App is installed on the **specific repository**, not just the org. Org-level installs default to "selected repositories"; new repos won't be covered until added.
+- **`@claude` mention isn't picked up** -- in EMU orgs, comments by external collaborators are blocked entirely. The trigger only fires for users who are members of the EMU enterprise.
+- **OAuth tokens generated with `claude setup-token`** authenticate against `api.anthropic.com`, not your GHEC tenant. They work on any GHEC flavor.
+- **`actions/create-github-app-token`** auto-detects `GITHUB_API_URL`. If you also use `actions/checkout` against another `.ghe.com` tenant, pass `github-api-url` explicitly to the token-generator step.
+
+## Reference
+
+- [Main Setup Guide](./setup.md)
+- [Cloud Providers](./cloud-providers.md) (Bedrock / Vertex / Foundry)
+- [FAQ](./faq.md)
+- GitHub docs: [About GitHub Enterprise Cloud with data residency](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency)
+- GitHub docs: [About Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users)
+
+> **Note on GitHub Enterprise Server (GHES)**: this guide does **not** cover GHES (the self-hosted appliance with hostnames like `github.your-company.com`). GHES support is tracked in related issues; the steps here may partially apply but the GHES API surface and runner environment differ.
diff --git a/docs/setup.md b/docs/setup.md
@@ -1,5 +1,7 @@
 # Setup Guide
 
+> **Using GitHub Enterprise Cloud?** See the [GitHub Enterprise Cloud setup guide](./github-enterprise-cloud.md) for GHEC-specific differences (data residency, EMU, SSO, IP allowlists).
+
 ## Manual Setup (Direct API)
 
 **Requirements**: You must be a repository admin to complete these steps.
@@ -19,6 +21,7 @@ If you prefer not to install the official Claude app, you can create your own Gi
 - You need more restrictive permissions than the official app
 - Organization policies prevent installing third-party apps
 - You're using AWS Bedrock or Google Vertex AI
+- You're on [GitHub Enterprise Cloud with data residency](./github-enterprise-cloud.md#ghec-with-data-residency-ghecom) (`*.ghe.com`)
 
 ### Option 1: Quick Setup with App Manifest (Recommended)