Skip to main content
Tembo on Kubernetes connects to GitHub through a GitHub App that you create for your install. GitHub sends users back to your install’s URLs, so each install needs its own app. Set it up before you deploy, so Tembo starts with GitHub configured. You create the app, keep its credentials in a Kubernetes Secret, and the chart reads the Secret through github.existingSecret. The credentials stay out of your Helm values and your deploy pipeline. If Tembo is already installed, the same steps apply, with an upgrade at the end. You need:
  • Your Tembo hostname, the ingress.host you deploy with (e.g. tembo.example.com).
  • kubectl access to the namespace you install Tembo in. The examples use release tembo in namespace tembo.
  • To create the app under a GitHub organization: an owner or GitHub App manager of that organization.

Step 1: Create the GitHub App

Open New GitHub App: https://github.com/organizations/<your-org>/settings/apps/new for an organization, or GitHub > Settings > Developer settings > GitHub Apps > New GitHub App for your account. Fill in: If GitHub can’t reach the webhook URL, for example behind an internal load balancer, uncheck Active under Webhook. Comments that mention Tembo, issue and pull request triggers, and pull request status updates then don’t work. Then click Create GitHub App. GitHub pings the webhook right away, and the ping fails until Tembo is running; that’s expected. You can redeliver it from the app’s Advanced tab after you deploy. Create a GitHub App describes each setting.
If Tembo is already installed without an app, helm get notes tembo -n tembo links to this form with your URLs, permissions and events filled in. Set github.organization in your values to have it link to an organization’s form. Use the webhook secret the chart generated rather than your own, and leave webhookSecret out of the Secret in Step 3:

Step 2: Generate a client secret and a private key

On the app’s settings page:
  1. Under Client secrets, click Generate a new client secret and copy it. GitHub shows it only once.
  2. Under Private keys, click Generate a private key. GitHub downloads a .pem file.
Also note the App ID, the Client ID, and the app’s slug, from its URL https://github.com/apps/<app slug>.

Step 3: Store the credentials in a Secret

Create the namespace if it doesn’t exist yet, then the Secret. clientUserEmail is your app’s bot noreply address, which uses the bot’s user ID from GitHub:
Replace each <...> with its value; in a shell, the angle brackets themselves would be read as redirects. Check that BOT_ID is a number: null means the slug is wrong. The Secret can hold any of these keys: Values in the Secret override the same keys under github in your Helm values.

Step 4: Point the chart at the Secret

In your values.yaml:
Then deploy with these values. The chart reads the Secret while rendering, so it must exist first. If it’s missing, the install fails with github.existingSecret: Secret tembo-github-app is missing. If Tembo is already installed, upgrade instead:
Agent hosts read the GitHub settings when they start; after the upgrade, the controller replaces them (see Apply changes).

Step 5: Connect GitHub

Once Tembo is deployed, connect GitHub from Tembo, not from GitHub: Tembo only accepts an installation that starts in Tembo.
  1. In Tembo, go to Settings > Integrations and connect GitHub.
  2. Choose the organization or account, and All repositories or specific ones, then click Install. GitHub then asks you to authorize the app.
  3. On the page Tembo opens next, enable the repositories Tembo should work on. You can change them later in Settings > Repositories.
To connect a GitHub organization, you need to be one of its owners. Otherwise GitHub sends the owners an installation request instead. This connects repositories to your workspace. For personal Connected accounts and signing in with GitHub, also configure GitHub sign-in. To check webhooks, open the app’s Advanced > Recent deliveries on GitHub after a matching event, such as a comment that mentions Tembo.

GitHub sign-in and connected accounts

The GitHub App under github connects repositories. Settings → Connected accounts → Connect GitHub and GitHub sign-in need separate betterAuth.oauth.github settings, even when repository integration works. You can reuse your GitHub App’s client ID and client secret:
  1. Add https://<your-host>/api/auth/callback/github as another callback URL in the App’s settings. Keep the repository integration’s /api/oauth/github/callback URL too.
  2. Set the App’s Account permissions → Email addresses to Read-only. Users approve this permission when authorizing the app.
  3. Create a Secret whose keys are config paths:
  4. Append it to configSecrets in your values, keeping any existing entries, then apply the change:
Secrets must exist before the upgrade: Helm reads configSecrets while rendering. With helm template, supply the same config paths under config from an encrypted values file instead. Enabling GitHub for connected accounts also enables GitHub sign-in and registration. Installing the GitHub App on a particular organization does not restrict who can sign up to Tembo. Users who register can create their own workspaces and consume your install’s compute, although they cannot see your existing workspace. See Sign-in and registration to control enabled providers or troubleshoot account linking.

Rotate credentials

  1. Generate a new client secret or private key on the app’s settings page.
  2. Update the Secret with the same kubectl create secret ... | kubectl apply command.
  3. Run helm upgrade again. The platform restarts with the new values.
  4. Wait for the controller to replace the running agent hosts, which read the new values when they start.
  5. Delete the old client secret or private key on GitHub.

GitOps and helm template

Argo CD, Flux and other tools that render the chart with helm template don’t give it access to your cluster, so it can’t read github.existingSecret. A generated webhook secret would also change on every render. Set the app’s values under github instead, from a values file you keep encrypted, including the webhook secret you entered in GitHub: