> ## 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 from self-hosted Overcut

> Connect GitHub.com to a self-hosted Overcut deployment by creating your own GitHub App.

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.

<Note>
  Not your setup? See [Which setup do I need?](/docs/integrations/github#which-setup-do-i-need).
  On **Overcut Cloud**, use the managed
  [Overcut GitHub App](/docs/integrations/github/cloud) instead - no app creation
  or environment configuration is needed there.
</Note>

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

<Steps>
  <Step title="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>`
  </Step>

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

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

    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.
  </Step>

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

    * **Active**: checked

    * **Webhook URL**:

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

    * **Webhook secret**: generate a strong random value and keep it - it goes
      into the deployment's `.env` as `GITHUB_WEBHOOK_SECRET`:

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

  <Step title="Set the permissions">
    Under **Permissions**, configure:

    **Repository permissions**

    | Permission    | Access                      | Why                                                                    |
    | ------------- | --------------------------- | ---------------------------------------------------------------------- |
    | Contents      | Read and write              | Clone repositories, create branches, push changes                      |
    | Issues        | Read and write              | Read, create, and comment on issues                                    |
    | Pull requests | Read and write              | Open, review, and comment on pull requests                             |
    | Metadata      | Read-only                   | Mandatory baseline (GitHub sets this automatically)                    |
    | Actions       | Read and write              | Receive CI events (`workflow_run`) and manage workflow runs            |
    | Workflows     | Read and write *(optional)* | Only if agents should create or modify files under `.github/workflows` |

    **Organization permissions**

    | Permission | Access    | Why                                                  |
    | ---------- | --------- | ---------------------------------------------------- |
    | Members    | Read-only | Resolve organization members for assignment features |
  </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**

    Other event types are ignored by Overcut.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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>
</Steps>

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

| Variable                      | Value                                                                |
| ----------------------------- | -------------------------------------------------------------------- |
| `GITHUB_APP_APP_ID`           | The **App ID**                                                       |
| `GITHUB_APP_CLIENT_ID`        | The **Client ID**                                                    |
| `GITHUB_APP_CLIENT_SECRET`    | The generated **client secret**                                      |
| `GITHUB_APP_PRIVATE_KEY`      | The private key as a **single line** with `\n` escapes (see below)   |
| `GITHUB_APP_INSTALLATION_URL` | `https://github.com/apps/<app-slug>/installations/new?state={state}` |
| `GITHUB_WEBHOOK_SECRET`       | The **webhook secret** you set on the app                            |
| `INTEGRATION_GITHUB_ENABLED`  | `true`                                                               |
| `DISPATCHER_BASE_URL`         | `https://<your-overcut-domain>/hooks`                                |

<Warning>
  Keep the literal `{state}` placeholder in `GITHUB_APP_INSTALLATION_URL` - do
  not replace it. Overcut substitutes the workspace identifier at connect time.
</Warning>

### 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:

```bash theme={null}
awk 'NF {sub(/\r/, ""); printf "%s\\n", $0}' <downloaded-key>.private-key.pem
```

Paste the output as the value of `GITHUB_APP_PRIVATE_KEY` (no surrounding
quotes needed). It should look like:

```
GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nMIIEow...\n-----END RSA PRIVATE KEY-----\n
```

### Apply the configuration

```bash theme={null}
docker compose up -d
```

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

## Step 3: Connect in Overcut

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

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](/docs/integrations/github).