Register the GitHub App
On the shared PhillipCLI service, the GitHub App already exists, and your organization only installs it (Connect GitHub). This page is for self-hosted installs, where you register the app yourself, once. It takes about 10 minutes.
What you need
- A GitHub account that can create the app: an owner of the GitHub organization that will own it, or your personal account. Customers install a public app from any organization, so the app can live anywhere; a company organization is the usual choice.
- Your Tara public address (
TARA_PUBLIC_URL). For webhooks to work it must be reachable from GitHub over HTTPS. Without that the app still works, with webhooks off (see Local development). - Shell access to a machine with
tara-adminand a browser. These commands need no database.
Register with one command
Run the setup command. Leave
--ownerout to create the app on your personal account.bashtara-admin github-app-setup --owner acme-corp \ --name PhillipCLI --public-url https://tara.example.com --out-dir ./github-appYour browser opens a page with one button. Sign in to GitHub if asked, press the button, review the settings GitHub shows, and confirm. The terminal waits up to 15 minutes (
--timeout). If the browser cannot be opened, the command prints the path of the page for you to open yourself.GitHub sends you back to a page served by the command on
127.0.0.1. It says you can return to the terminal, and the command writestara-github-app.envandtara-github-app.peminto--out-dir.Load
github-app/tara-github-app.envinto the environment oftara-api, keeptara-github-app.pemwheretara-apican read it, and restart. With the single-host Compose files, copy the PEM todeploy/single-host/secrets/github-app.pem(owner uid 10001, mode 400) and setTARA_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/tara/github-app.pem; Compose mounts that directory read-only. On Helm, put the PEM in a Secret and setgithubApp.privateKey.existingSecret. The variables are described in Self-hosting reference.
--public-url defaults to TARA_PUBLIC_URL when that is set. --listen changes the local address that receives GitHub's redirect (loopback addresses only; the default picks a free port on 127.0.0.1).
The command writes the two files readable only by you (mode 600). It never overwrites an existing file, checks that before it opens the browser, and never prints a secret. Keep both files out of git, and move them to your secret store.
tara-api also logs a warning at startup while no GitHub App is configured, so you can see that customers cannot connect a GitHub organization yet.
Local development
On localhost the command works as is. Run Tara with the default TARA_PUBLIC_URL=http://localhost:8080 and run the same command. GitHub cannot deliver webhooks to localhost or to a plain http address, so the command registers the app with the webhook switched off and prints a warning. Everything else works. Changes to an installation, such as new repositories, reach Tara on the next setup redirect or the hourly sync instead of instantly. Register again with an https public address when you want webhooks.
Register in two steps (manual alternative)
The one-command flow is the same manifest flow, split in two. Use this when the browser and the shell are on different machines.
Generate the registration page.
--owneris optional here too.bashtara-admin github-app-manifest --owner acme-corp \ --name PhillipCLI --public-url https://tara.example.com --out register-app.htmlOpen
register-app.htmlin a browser signed in to GitHub, click the button, review the settings GitHub shows, and confirm.GitHub sends you to your public address with
?code=...in the address bar. Copy the code. It works once and expires after an hour.Exchange the code for the app's credentials, then continue as in step 4 above.
bashtara-admin github-app-convert --code <code> --out-dir ./github-app
Use --redirect-url to send GitHub somewhere else after registration, and leave --out off to print the page to the terminal. A localhost or http public address turns the webhook off here as well.
What the manifest sets
| Setting | Value |
|---|---|
| Visibility | Public, so customers can install it on their own organizations |
| Webhook URL | <TARA_PUBLIC_URL>/webhooks/github; switched off for a localhost or http address |
| Setup URL | <TARA_PUBLIC_URL>/auth/github-app/setup |
| Callback URLs | <TARA_PUBLIC_URL>/auth/github-app/setup and <TARA_PUBLIC_URL>/auth/scm-user/callback (the second serves the one-click Connect GitHub button in Bandum) |
| Request user authorization (OAuth) during installation | On |
| Redirect on update | On |
| Repository permissions | Contents, Issues, Pull requests: read and write; Metadata: read-only |
| Organization permission | Members: read-only |
| Events | Organization, Membership, Push, Repository (GitHub always sends Installation and Installation repositories) |
Apart from one button, the app itself never writes to a repository: Create standard labels on the project page (owners and admins) creates the status:, type: and level: labels with a short-lived installation token limited to that repository and to Issues: write (ph bandum labels init does the same with the developer's own token). Without Issues: write on an installation, the button answers issues_write_required and the owner of the GitHub account has to accept the new permission request. The write permissions exist so that a person who clicks Connect GitHub in Bandum can record test results as themselves: the token GitHub then issues acts as that person and can never exceed what the app is allowed. The tokens Tara hands to Ryoma and Bandum for syncing stay read-only, because Tara always asks GitHub for read permissions explicitly. If your app was registered earlier with read-only permissions, raise Contents, Issues and Pull requests to read and write, add the second callback URL, and turn on Expire user authorization tokens; each organization that installed the app then has to accept the new permissions. See docs/design/scm-user-token.md.
Register by hand
Prefer the GitHub screens? Create the app under your organization's Settings › Developer settings › GitHub Apps with the values above, then generate a private key and a client secret. Set the six variables yourself.
Check it works
Open Settings › GitHub in Tara as an Owner or Admin and click Connect GitHub. GitHub should open the install page of your app. Without all six variables, the feature stays off. With only some of them, Tara refuses to start, which keeps a half-configured app from running.