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, 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
On Kubernetes, follow GitHub on Kubernetes: the install notes link to this page with your install’s URLs, permissions and events filled in. This page describes each setting.
- 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
Callback URL
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
Webhook secret
Generate a random string (for example withopenssl 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.
Permissions
Under Repository permissions, set:
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
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
.pemfile will be downloaded — you will need its full contents for the config
Step 4: Configure Tembo
Tembo needs these values from your GitHub App:
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:
Kubernetes
Store the values in a Kubernetes Secret that the chart reads throughgithub.existingSecret; see GitHub on Kubernetes. 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.- 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.