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

# GitHub

> Set up the GitHub App integration for Tembo self-hosted.

## Overview

The GitHub integration allows Tembo to clone repositories, create branches, push commits, open pull requests, and respond to issues and webhooks. On the SaaS platform this is pre-configured — on self-hosted you need to create your own GitHub App and point it at your instance.

These steps are for a single instance. On Kubernetes, follow [GitHub on Kubernetes](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md), which keeps the app's credentials in a Kubernetes Secret and links back here for the app's settings.

In the URLs below, `<your-tembo-url>` is the address you open Tembo at: `http://<your-instance-ip>` on a single instance, or your Ingress host on Kubernetes (e.g. `https://tembo.example.com`).

***

## Step 1: Create a GitHub App

> [!NOTE]
>
> On Kubernetes, follow [GitHub on Kubernetes](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md): the install notes link to this page with your install's URLs, permissions and events filled in. This page describes each setting.

1. Go to **GitHub > Settings > Developer settings > GitHub Apps > New GitHub App**

### GitHub App name

Choose a name for your app, e.g. `Tembo (self-hosted)`. This will be visible to users when they install the app.

### Homepage URL

```
<your-tembo-url>
```

### Callback URL

```
<your-tembo-url>/api/oauth/github/callback
```

This is where GitHub redirects users after they authorize the app.

### Check **Request user authorization (OAuth) during installation**

This is important — it ensures that when a user installs the app, they are also prompted to authorize Tembo to act on their behalf. Without this, Tembo cannot perform actions as the installing user.

### Webhook URL

```
<your-tembo-url>/api/webhook/github
```

GitHub must be able to reach this URL to deliver events. If your instance isn't reachable from the internet, for example behind an internal load balancer, uncheck **Active**. Tembo still works, but anything GitHub triggers won't: comments that mention Tembo, issue and pull request triggers, and pull request status updates.

### Webhook secret

Generate a random string (for example with `openssl rand -hex 32`) and enter it here. Save this value — you will need it for the Tembo config later.

On Kubernetes, store it in the app's Kubernetes Secret, or use the one the Helm chart generates; see [GitHub on Kubernetes](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md#step-1-create-the-github-app).

### Permissions

Under **Repository permissions**, set:

| Permission | Access |
| - | - |
| **Actions** | Read-only |
| **Checks** | Read & write |
| **Commit statuses** | Read-only |
| **Contents** | Read & write |
| **Issues** | Read & write |
| **Metadata** | Read-only |
| **Pull requests** | Read & write |
| **Webhooks** | Read & write |

Under **Organization permissions**, set **Members** to **Read-only**. Tembo uses it to check that whoever connects an organization is one of its owners; without it, connecting fails with **Failed to get extra data for integration**. It also enables the Member, Organization, Team, and Team add event subscriptions.

Under **Account permissions**, no changes are needed.

### Subscribe to events

Check the following:

* Check run
* Commit comment
* Create
* Delete
* Issue comment
* Issues
* Member
* Organization
* Pull request
* Pull request review
* Pull request review comment
* Pull request review thread
* Push
* Release
* Repository
* Status
* Team
* Team add
* Workflow run

If you already have a GitHub App, open **Permissions & events**, enable any missing events, and save your changes. If you change permissions, approve the updated permissions for the app's installation when prompted.

Agent triggers require the corresponding GitHub event subscription. For example, a **Release Published** trigger will not run unless you enable **Release**. Enabling a subscription does not replay past events.

### Where can this GitHub App be installed?

Select **Only on this account** if you only need it for a single org. Select **Any account** if you want to install it across multiple orgs.

### Create the app

Click **Create GitHub App**.

***

## Step 2: Generate a Client Secret

After the app is created, you will be on the app settings page.

1. Under **Client secrets**, click **Generate a new client secret**
2. Copy the secret immediately — it will only be shown once

***

## Step 3: Generate a Private Key

Still on the app settings page:

1. Scroll down to **Private keys**
2. Click **Generate a private key**
3. A `.pem` file will be downloaded — you will need its full contents for the config

***

## Step 4: Configure Tembo

Tembo needs these values from your GitHub App:

| Key | Where to find it |
| - | - |
| `github.appId` | App settings page, listed as **App ID** |
| `github.appName` | The slug of your app name (e.g. `tembo-self-hosted`) |
| `github.clientId` | App settings page, listed as **Client ID** |
| `github.clientSecret` | The client secret you generated in Step 2 |
| `github.privateKey` | Contents of the `.pem` file from Step 3 (include the full key with newlines) |
| `github.webhookSecret` | The random string you set as the webhook secret in Step 1 |
| `github.clientUserName` | Your app's bot, `<app slug>[bot]` |
| `github.clientUserEmail` | Your bot's noreply email, `<bot user ID>+<app slug>[bot]@users.noreply.github.com`. The bot user ID is the `id` at `https://api.github.com/users/<app slug>%5Bbot%5D` |
| `github.botTagName` | The mention Tembo answers in comments, `@<app slug>` |

Tembo commits as `github.clientUserName` and `github.clientUserEmail`, and treats pull requests and comments by `github.clientUserName` as its own. Without these values, Tembo uses the identity of Tembo's cloud app: it answers `@staging-tembo` mentions, and its commits are attributed to Tembo's app.

### Single instance

Open `/var/lib/tembo/config.json` (via the VS Code server at `http://<your-instance-ip>:8888` or via SSH) and add the following keys:

```json theme={null}
{
  "github.appId": "<your-github-app-id>",
  "github.appName": "<your-github-app-name>",
  "github.clientId": "<your-github-app-client-id>",
  "github.clientSecret": "<your-github-app-client-secret>",
  "github.privateKey": "<contents-of-the-pem-file>",
  "github.webhookSecret": "<your-webhook-secret>",
  "github.clientUserName": "<app-slug>[bot]",
  "github.clientUserEmail": "<bot-user-id>+<app-slug>[bot]@users.noreply.github.com",
  "github.botTagName": "@<app-slug>"
}
```

After saving, restart the API:

```bash theme={null}
sudo systemctl restart tembo-ts-api
```

Updating the config.json will also cause the instance api to restart automatically.

### Kubernetes

Store the values in a Kubernetes Secret that the chart reads through `github.existingSecret`; see [GitHub on Kubernetes](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md). It also covers GitOps tools that render the chart with `helm template`.

***

## Step 5: Connect GitHub

Install the app from Tembo, not from GitHub: Tembo only accepts the installation when the connection starts in Tembo.

To connect a GitHub organization, you need to be an owner of it on GitHub. If you aren't, GitHub sends your organization's owners an installation request instead, and Tembo asks you to have an owner connect GitHub.

1. Go to your Tembo instance and navigate to **Settings > Integrations**
2. Connect GitHub
3. Select the organization or account to install the app on, and choose **All repositories** or specific repositories
4. Click **Install** — because you checked **Request user authorization (OAuth) during installation**, you will be redirected to authorize the app as well
5. On the page Tembo opens next, enable the repositories Tembo should work on. You can change them later in **Settings > Repositories**. Sessions can't clone a repository that isn't enabled.

***

## Step 6: Verify

1. In **Settings > Integrations**, confirm GitHub shows as connected
2. Try creating a session against one of the repositories you installed the app on
3. Test an agent trigger with a new matching event, then check the GitHub App's **Advanced > Recent deliveries** for a successful delivery to your instance. A successful delivery shows that GitHub reached Tembo, not that the webhook secrets match: Tembo also answers deliveries it rejects with 200. If nothing happens in Tembo, check that the webhook secret in GitHub matches `github.webhookSecret`.

***

## Need Help?

If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.