diff --git a/README.md b/README.md index b8301f71a..4f526bdab 100644 --- 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 new file mode 100644 index 000000000..4c71386d3 --- /dev/null +++ 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 index e0c7f56c8..695372d3a 100644 --- 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)