> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Enterprise Server

> Connect a GitHub Enterprise Server instance to a self-hosted Overcut deployment by creating a GitHub App on your instance.

Use this path when you run **Overcut on your own infrastructure** and your code
lives on **GitHub Enterprise Server** (GHES). You create a GitHub App on your
GHES instance and configure the deployment with its credentials. Tokens,
webhooks, and repository access stay between your GHES instance and your
deployment.

GitHub Enterprise Server is a separate provider from **GitHub**. A deployment
can connect one GHES instance, and it can run alongside github.com connections
in the same workspace. Each connection shows its provider label in
**Integrations**, so you can tell them apart.

<Note>
  Not your setup? See [Which setup do I need?](/docs/integrations/github#which-setup-do-i-need).
  GitHub Enterprise Server can only be connected from a **self-hosted Overcut**
  deployment. For github.com, use the [managed Overcut GitHub App](/docs/integrations/github/cloud)
  (Overcut Cloud) or [your own GitHub App](/docs/integrations/github/self-hosted)
  (self-hosted Overcut).
</Note>

## Prerequisites

* **GitHub Enterprise Server 3.12 or later**, with admin access to an
  organization (or user account) that can create and install GitHub Apps
* A running self-hosted Overcut deployment with an HTTPS domain
  (`https://<your-overcut-domain>`)
* **Network access in both directions**:
  * Overcut, including the agent environments it starts, reaches your GHES host
    over HTTPS (web, API, and git over HTTPS)
  * Your GHES instance reaches `https://<your-overcut-domain>/hooks/...` to
    deliver webhooks
* **A GHES TLS certificate issued by a public certificate authority.** Private
  CA bundles are not supported yet.
* The ability to set environment variables on the deployment and restart it

## Step 1: Create the GitHub App on GHES

<Steps>
  <Step title="Start a new GitHub App">
    On your GHES instance, go to **Settings -> Developer settings -> GitHub
    Apps -> New GitHub App**, under the organization or user that should own
    the app.

    * **GitHub App name**: something identifiable, for example `Overcut`.
    * **Homepage URL**: `https://<your-overcut-domain>`
  </Step>

  <Step title="Set the callback URL and enable user authorization">
    Under **Identifying and authorizing users**, set **Callback URL** to:

    ```
    https://<your-overcut-domain>/github-enterprise-auth-app/callback
    ```

    Check **Request user authorization (OAuth) during installation**. This is
    required: without it, connecting from Overcut fails.
  </Step>

  <Step title="Configure the webhook">
    Under **Webhook**:

    * **Active**: checked

    * **Webhook URL**:

      ```
      https://<your-overcut-domain>/hooks/github/enterprise/webhook
      ```

    * **Webhook secret**: generate a strong random value and keep it. You set
      it on the deployment as `GITHUB_ENTERPRISE_WEBHOOK_SECRET` in Step 2:

      ```bash theme={"dark"}
      openssl rand -hex 32
      ```
  </Step>

  <Step title="Set the permissions">
    Grant the same repository and organization permissions as the github.com
    app. See [Set the permissions](/docs/integrations/github/self-hosted#step-1-create-the-github-app)
    in the self-hosted GitHub guide for the full table.
  </Step>

  <Step title="Subscribe to events">
    Under **Subscribe to events**, enable exactly these:

    * **Issues**
    * **Issue comment**
    * **Pull request**
    * **Pull request review**
    * **Pull request review comment**
    * **Pull request review thread**
    * **Workflow run**

    Click **Create GitHub App**.
  </Step>

  <Step title="Collect the credentials">
    From the app's settings page, collect:

    * **App ID**
    * **Client ID**
    * **Client secret**: click **Generate a new client secret**
    * **Private key**: click **Generate a private key**; a `.pem` file downloads
    * **App slug**: the URL-safe name in the app's public link
      (`https://<ghes-host>/github-apps/<app-slug>`)
  </Step>
</Steps>

## Step 2: Configure the deployment

Set these environment variables on your deployment:

| Variable | Value |
| - | - |
| `INTEGRATION_GITHUB_ENTERPRISE_ENABLED` | `true` (off by default) |
| `GITHUB_ENTERPRISE_URL` | Your GHES web URL, for example `https://ghe.example.com` |
| `GITHUB_ENTERPRISE_APP_ID` | The **App ID** |
| `GITHUB_ENTERPRISE_APP_CLIENT_ID` | The **Client ID** |
| `GITHUB_ENTERPRISE_APP_CLIENT_SECRET` | The generated **client secret** |
| `GITHUB_ENTERPRISE_APP_PRIVATE_KEY` | The private key as a **single line** with `\n` escapes |
| `GITHUB_ENTERPRISE_APP_INSTALLATION_URL` | `https://<ghes-host>/github-apps/<app-slug>/installations/new` |
| `GITHUB_ENTERPRISE_WEBHOOK_SECRET` | The **webhook secret** you set on the app |

Format the private key the same way as for the github.com app. See
[Private key formatting](/docs/integrations/github/self-hosted#private-key-formatting).

If your deployment sets environment variables per service, set
`INTEGRATION_GITHUB_ENTERPRISE_ENABLED` on both the API server and the webhook
service. With only the API server enabled, organizations connect but webhooks
are rejected and no workflow triggers.

Restart the deployment so the new environment variables take effect.

## Step 3: Connect in Overcut

<Steps>
  <Step title="Start the connection">
    In Overcut, open **Integrations**, select **Add Provider**, then choose
    **GitHub Enterprise Server**. Your GHES instance opens in a popup.
  </Step>

  <Step title="Install the app">
    Choose the account or organization to install into, then select the
    repositories the app may access. Complete the installation.

    The popup closes and Overcut shows **Connected successfully**. The
    organization appears in **Integrations** with the **GitHub Enterprise
    Server** provider label.
  </Step>

  <Step title="Register and activate repositories">
    Open the GitHub Enterprise Server connection, select **Add Repositories**,
    and register the repositories you want Overcut to use. Then set each one to
    **Active**. See [Repositories](/docs/get-started/repositories).
  </Step>

  <Step title="Verify webhook delivery">
    In the GitHub App's settings on GHES, open **Advanced -> Recent
    Deliveries** and confirm the response code is **200**. Comment on a test
    issue in a connected repository to produce a delivery.
  </Step>
</Steps>

Once connected, GHES repositories work like github.com repositories: triggers,
agent tools, `git.clone`, and `ci.executeWorkflow` all support them. In a
[repository selector](/docs/repositories/repository-selector), set **Git
Provider** to **GitHub Enterprise Server** to target only GHES repositories.

## Troubleshooting

* **GitHub Enterprise Server is missing from Add Provider**:
  `INTEGRATION_GITHUB_ENTERPRISE_ENABLED` is not `true`, or the deployment was
  not restarted after setting it.
* **"GitHub Enterprise Server is not configured"**: `GITHUB_ENTERPRISE_URL` is
  empty or does not point to a GHES web URL.
* **Connect popup shows a 404 on GHES**: the app slug in
  `GITHUB_ENTERPRISE_APP_INSTALLATION_URL` does not match your app's public
  URL.
* **"Authentication popup was blocked or failed"**: allow popups for Overcut in
  your browser, then start the connection again from **Integrations**.
* **"Missing GitHub authorization code"**: **Request user authorization (OAuth)
  during installation** is not enabled on the app. Enable it and connect again.
* **Popup stays on "Please wait..." and never closes**: the app's **Callback
  URL** is missing or wrong. It must be exactly
  `https://<your-overcut-domain>/github-enterprise-auth-app/callback`.
* **Deliveries return 200 but the response shows `Invalid webhook signature`**:
  the app's webhook secret and `GITHUB_ENTERPRISE_WEBHOOK_SECRET` do not match.
* **Webhook deliveries time out**: GHES cannot reach
  `https://<your-overcut-domain>/hooks/github/enterprise/webhook`. Check DNS,
  the TLS certificate, and firewall rules between the two networks.
* **Clones or API calls fail with certificate errors**: the GHES certificate is
  not trusted by Overcut. Use a certificate issued by a public certificate
  authority.
* **Workflows never trigger even though deliveries return 200**: the relevant
  event type is not enabled on the app, or the repository is not registered
  and **Active** in Overcut.

For what agents can do once connected, see the
[GitHub overview](/docs/integrations/github).