GitHub

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 apply to every self-hosted install. Only Step 4 differs between a single instance and Kubernetes. 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

On Kubernetes, helm install prints a link that opens this page with a name, a description, and your install’s URLs, permissions and events already filled in. Open it, check the settings below, and create the app. Change the name if GitHub says it’s taken.The link creates the app under your personal account. To create it under a GitHub organization, which needs an owner or GitHub App manager of the organization, set github.organization to the organization’s name in your Helm values.

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, the Helm chart generates one for you; the install notes show the command that prints it.

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

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

Step 3: Generate a Private Key

Still on the app settings page:

Scroll down to Private keys
Click Generate a private key
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:

{
  "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:

sudo systemctl restart tembo-ts-api

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

Kubernetes

Add the values to your Helm values file:

github:
  appId: "<your-github-app-id>"
  appName: "<your-github-app-name>"
  clientId: "<your-github-app-client-id>"
  clientSecret: "<your-github-app-client-secret>"
  clientUserEmail: "<bot-user-id>+<app-slug>[bot]@users.noreply.github.com"

The chart sets github.clientUserName and github.botTagName from appName (<app-slug>[bot] and @<app-slug>). Set them in github and config only to use different ones. Then pass the private key from its file when you upgrade:

helm upgrade tembo ./tembo-<version>.tgz -n tembo -f tembo-aws.json -f values.yaml \
  --set-file github.privateKey=<path-to-the-pem-file>

If you set your own webhook secret in Step 1, add it as github.webhookSecret. The chart passes these values to the platform and to agent hosts, so replace the running hosts afterwards (see Apply changes). To keep the credentials out of your values, put the same keys (appId, privateKey, …) in a Kubernetes Secret and set github.existingSecret to its name instead.

If you render the chart with helm template (for example with Argo CD or Flux), the chart can’t read github.existingSecret, and a generated webhook secret would change on every render. Set the github values from an encrypted values file instead, including github.webhookSecret with the value you entered in GitHub.

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.

Go to your Tembo instance and navigate to Settings > Integrations
Connect GitHub
Select the organization or account to install the app on, and choose All repositories or specific repositories
Click Install — because you checked Request user authorization (OAuth) during installation, you will be redirected to authorize the app as well
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

In Settings > Integrations, confirm GitHub shows as connected
Try creating a session against one of the repositories you installed the app on
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.

Get Started

Features

Actions

Integrations

Other

Overview

Step 1: Create a GitHub App

GitHub App name

Homepage URL

Callback URL

Check Request user authorization (OAuth) during installation

Webhook URL

Webhook secret

Permissions

Where can this GitHub App be installed?

Create the app

Step 2: Generate a Client Secret

Step 3: Generate a Private Key

Step 4: Configure Tembo

Single instance

Kubernetes

Step 5: Connect GitHub

Step 6: Verify

Need Help?

​Overview

​Step 1: Create a GitHub App

​GitHub App name

​Homepage URL

​Callback URL

​Check Request user authorization (OAuth) during installation

​Webhook URL

​Webhook secret

​Permissions

​Subscribe to events

​Where can this GitHub App be installed?

​Create the app

​Step 2: Generate a Client Secret

​Step 3: Generate a Private Key

​Step 4: Configure Tembo

​Single instance

​Kubernetes

​Step 5: Connect GitHub

​Step 6: Verify

​Need Help?

Overview

Step 1: Create a GitHub App

GitHub App name

Homepage URL

Callback URL

Check Request user authorization (OAuth) during installation

Webhook URL

Webhook secret

Permissions

Subscribe to events

Where can this GitHub App be installed?

Create the app

Step 2: Generate a Client Secret

Step 3: Generate a Private Key

Step 4: Configure Tembo

Single instance

Kubernetes

Step 5: Connect GitHub

Step 6: Verify

Need Help?