Skip to main content
Use this path when you run Overcut on your own infrastructure and your code lives on GitHub.com. Instead of the managed Overcut GitHub App, your deployment uses a GitHub App that you create and own. All tokens, webhooks, and repository access stay between your GitHub organization and your deployment; nothing goes through Overcut Cloud.
Not your setup? See Which setup do I need?. On Overcut Cloud, use the managed Overcut GitHub App instead - no app creation or environment configuration is needed there.

​
Prerequisites

  • A GitHub organization (or personal account) with admin access, so you can create and install GitHub Apps
  • A running self-hosted Overcut deployment with a public HTTPS domain (https://<your-overcut-domain>)
  • Inbound reachability from GitHub.com: GitHub must be able to deliver webhooks to https://<your-overcut-domain>/hooks/... over port 443
  • The ability to set environment variables on the deployment and restart it

​
How it works

Your GitHub App is the identity Overcut uses on GitHub:
  1. API access - Overcut authenticates as the app installation and gets short-lived installation tokens to clone repositories, open pull requests, and manage issues. No personal access tokens are involved.
  2. Webhooks - GitHub delivers events (issues, pull requests, comments, CI runs) to your deployment, signed with the webhook secret you configure.
The effective access is always the app’s permissions intersected with the repositories you select when installing the app.

​
Step 1: Create the GitHub App

1

Start a new GitHub App

In your GitHub organization, go to Settings -> Developer settings -> GitHub Apps -> New GitHub App (for a personal account: Settings -> Developer settings -> GitHub Apps).
  • GitHub App name: something identifiable, for example Overcut (Acme). The name determines the app slug used in the installation URL.
  • 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.Under Post installation, the Setup URL field is disabled once user authorization is enabled. GitHub redirects to the callback URL instead.
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_WEBHOOK_SECRET in Step 2:
4

Set the permissions

Under Permissions, configure:Repository permissionsOrganization permissions
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
Other event types are ignored by Overcut.
6

Choose where the app can be installed

Select Only on this account (recommended) unless you need to install the same app into multiple GitHub organizations.Click Create GitHub App.
7

Collect the credentials

From the app’s settings page, collect:
  • App ID (shown in the About section)
  • 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 visible in the app’s public link (https://github.com/apps/<app-slug>)

​
Step 2: Configure the deployment

Set these environment variables on your deployment:
Keep the literal {state} placeholder in GITHUB_APP_INSTALLATION_URL - do not replace it. Overcut substitutes the workspace identifier at connect time.

​
Private key formatting

The value must be a single line, so the downloaded PEM must be flattened with literal \n sequences in place of newlines (Overcut converts them back at runtime). Generate the value with:
Paste the output as the value of GITHUB_APP_PRIVATE_KEY (no surrounding quotes needed). It should look like:

​
Apply the configuration

Restart the deployment so the new environment variables take effect.

​
Step 3: Connect in Overcut

1

Start the connection

In Overcut, open your workspace’s git providers page and click Connect on the GitHub tile. A popup opens on your GitHub App’s installation page.
2

Install the app

Choose the account or organization to install into, then select All repositories or specific repositories. Click Install & Authorize.GitHub redirects back to your deployment, the popup closes itself, and the GitHub organization appears as connected in Overcut.
3

Verify webhook delivery

In the GitHub App’s settings, open Advanced -> Recent Deliveries, open any delivery (or comment on a test issue in a connected repository to produce one), and confirm the response code is 200.
To add or remove repositories later, use the installation’s Configure page on GitHub (Organization settings -> GitHub Apps -> your app -> Configure); Overcut picks up the change automatically.

​
Troubleshooting

  • GitHub tile missing or disabled in Overcut: INTEGRATION_GITHUB_ENABLED is not true, or the deployment was not restarted after setting it.
  • Connect popup shows a GitHub 404: the app slug in GITHUB_APP_INSTALLATION_URL does not match your app’s public URL (https://github.com/apps/<app-slug>).
  • “Missing GitHub authorization code”: Request user authorization (OAuth) during installation is not enabled on the app. Enable it and connect again.
  • “Missing GitHub OAuth client configuration”: GITHUB_APP_CLIENT_ID or GITHUB_APP_CLIENT_SECRET is empty on the deployment.
  • “GitHub authorization code exchange failed”: the client ID and secret do not belong to the same app as GITHUB_APP_APP_ID, or the connection was retried by reloading the callback page. Start again from the Integrations page.
  • “This GitHub installation is not accessible to your GitHub account”: the GitHub account that finished the install cannot see that installation. Sign in as a member of the organization that owns it.
  • 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-auth-app/callback.
  • “Missing Github configuration” in the deployment logs: one of GITHUB_APP_APP_ID, GITHUB_APP_PRIVATE_KEY, or GITHUB_APP_INSTALLATION_URL is empty, or the private key was pasted with real line breaks instead of \n escapes.
  • Webhook deliveries fail with 401: the app’s webhook secret and GITHUB_WEBHOOK_SECRET do not match.
  • Webhook deliveries time out: GitHub.com cannot reach https://<your-overcut-domain>/hooks/github/webhook - check DNS, the TLS certificate, and that port 443 is open to the internet.
  • Workflows never trigger even though deliveries return 200: the relevant event type is not enabled on the app (see the event list above), or the repository is not included in the app installation.
  • CI-triggered workflows never fire: the app is missing the Actions permission or the Workflow run event subscription.
  • Pushes that touch .github/workflows are rejected: grant the app the Workflows: Read and write permission, then approve the permission update on the installation.
  • After changing app permissions nothing happens: permission changes must be approved on the installation by an organization admin (GitHub sends the org an approval request).
For what agents can do once connected (repositories, issues, pull requests, triggers), see the GitHub overview.