Skip to main content
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.
Not your setup? See 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 (Overcut Cloud) or your own GitHub App (self-hosted Overcut).

​
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

1

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

Set the callback URL and enable user authorization

Under Identifying and authorizing users, set Callback URL to:
Check Request user authorization (OAuth) during installation. This is required: without it, connecting from Overcut fails.
3

Configure the webhook

Under Webhook:
  • Active: checked
  • Webhook URL:
  • Webhook secret: generate a strong random value and keep it. You set it on the deployment as GITHUB_ENTERPRISE_WEBHOOK_SECRET in Step 2:
4

Set the permissions

Grant the same repository and organization permissions as the github.com app. See Set the permissions in the self-hosted GitHub guide for the full table.
5

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.
6

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 2: Configure the deployment

Set these environment variables on your deployment: Format the private key the same way as for the github.com app. See 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

1

Start the connection

In Overcut, open Integrations, select Add Provider, then choose GitHub Enterprise Server. Your GHES instance opens in a popup.
2

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.
3

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.
4

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.
Once connected, GHES repositories work like github.com repositories: triggers, agent tools, git.clone, and ci.executeWorkflow all support them. In a 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.