Skip to main content
Use this path when you run Overcut on your own infrastructure (for example the Docker Compose standalone deployment) 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
  • Access to the deployment’s .env file and the ability to restart the stack

​
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’s dispatcher endpoint, 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 and setup URLs

Under Identifying and authorizing users, set Callback URL to:
Under Post installation, set Setup URL to the same value. This is required: after a user installs the app, GitHub redirects here with the installation_id that Overcut stores to complete the connection.
3

Configure the webhook

Under Webhook:
  • Active: checked
  • Webhook URL:
  • Webhook secret: generate a strong random value and keep it - it goes into the deployment’s .env as GITHUB_WEBHOOK_SECRET:
4

Set the permissions

Under Permissions, configure:Repository permissions
PermissionAccessWhy
ContentsRead and writeClone repositories, create branches, push changes
IssuesRead and writeRead, create, and comment on issues
Pull requestsRead and writeOpen, review, and comment on pull requests
MetadataRead-onlyMandatory baseline (GitHub sets this automatically)
ActionsRead and writeReceive CI events (workflow_run) and manage workflow runs
WorkflowsRead and write (optional)Only if agents should create or modify files under .github/workflows
Organization permissions
PermissionAccessWhy
MembersRead-onlyResolve organization members for assignment features
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

Add the credentials to the deployment’s .env file. In the Docker Compose standalone deployment these variables are wired to both the API server and the workflow dispatcher automatically.
VariableValue
GITHUB_APP_APP_IDThe App ID
GITHUB_APP_CLIENT_IDThe Client ID
GITHUB_APP_CLIENT_SECRETThe generated client secret
GITHUB_APP_PRIVATE_KEYThe private key as a single line with \n escapes (see below)
GITHUB_APP_INSTALLATION_URLhttps://github.com/apps/<app-slug>/installations/new?state={state}
GITHUB_WEBHOOK_SECRETThe webhook secret you set on the app
INTEGRATION_GITHUB_ENABLEDtrue
DISPATCHER_BASE_URLhttps://<your-overcut-domain>/hooks
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

.env values are 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

Compose recreates the services whose environment changed (the API server and the workflow dispatcher).

​
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.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 services were not recreated after editing .env.
  • 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>).
  • Popup stays on “Please wait…” and never closes: the app’s Setup URL is missing or wrong. It must be exactly https://<your-overcut-domain>/github-auth-app/callback so the redirect carries the installation_id back to Overcut.
  • “Missing Github configuration” in the server 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.