Skip to content

github-enterprise-cloud.md

Latest commit

 

History

History
137 lines (95 loc) · 8.73 KB

github-enterprise-cloud.md

File metadata and controls

137 lines (95 loc) · 8.73 KB

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 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 and the main Setup Guide 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, the marketplace Claude app cannot be installed into EMU organizations. Use the Custom GitHub App path 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, 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. 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 -- 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:

- 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 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)

  5. Use the custom-app token in your workflow, the same way as in the Custom GitHub App section:

    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 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). 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) if https://bun.sh is blocked.

Common Gotchas

  • 403 Resource not accessible by integration from /user -- previously a known issue on Enterprise instances (#520). Fixed by the bot_id / bot_name defaults; see the FAQ entry.
  • 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

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.