Skip to content

Self-hosting reference ​

This page lists the variables that turn on the sign-in and GitHub features of a self-hosted Tara, with Ryoma and Bandum. The general groups are in Configuration variables. Every value below is a placeholder. Keep real secrets in your secret store, not in git.

With Docker Compose, put the values in the environment file of the install (the template lists all of them, commented). With Helm, put secrets in the chart's Secret and the rest in config or extraEnv (Deploy with Helm).

Sign-in ​

VariableDefaultMeaning
TARA_PUBLIC_URLhttp://localhost:8080Public address. OAuth callbacks, the GitHub App, and SSO all hang off it
TARA_GOOGLE_CLIENT_ID, TARA_GOOGLE_CLIENT_SECRETemptyBoth set: Google sign-in is on. Register the callback <TARA_PUBLIC_URL>/auth/google/callback. Only accounts with a verified email can sign in
TARA_SMTP_URLemptyMail server for invitations and sign-in links: smtp://user:pass@host:587 (STARTTLS when offered) or smtps://user:pass@host:465
TARA_MAIL_FROMemptySender, for example PhillipCLI <no-reply@example.com>

Without TARA_SMTP_URL, mail is only logged. In production (TARA_ENV=production) email sign-in is then unavailable, because nobody would receive the link. See Sign-in options.

GitHub App ​

Set all six or none. Some but not all is a startup error. The quick way to get the values is Register the GitHub App.

VariableDefaultMeaning
TARA_GITHUB_APP_IDemptyThe app's numeric ID
TARA_GITHUB_APP_SLUGemptyThe app's short name in its GitHub address
TARA_GITHUB_APP_PRIVATE_KEY_FILEemptyPath to the app's private key (PEM), parsed at startup. Keep it out of images. With the single-host Compose files, put the PEM in the secrets directory next to docker-compose.yml (or TARA_SECRETS_DIR), owned by uid 10001 with mode 400, and set /run/secrets/tara/github-app.pem. On Helm, use githubApp.privateKey.existingSecret
TARA_GITHUB_APP_WEBHOOK_SECRETemptySigns webhooks, at least 16 characters
TARA_GITHUB_APP_CLIENT_ID, TARA_GITHUB_APP_CLIENT_SECRETemptyThe app's OAuth credentials, used to check who is installing it
TARA_GITHUB_API_URLhttps://api.github.comGitHub API address. Change it for GitHub Enterprise Server
TARA_GITHUB_SYNC_INTERVAL1hHow often Tara refreshes repositories and members. 0 turns the periodic sync off
TARA_GITHUB_IMPORT_TOKENemptyOptional. Raises GitHub's rate limit when importing public repositories. It reads public data only

Secrets for organization SSO ​

Organizations store their SSO client secret encrypted. Choose one key source:

VariableMeaning
TARA_SECRET_KEYA local key: 32 random bytes as 64 hex characters or base64 (openssl rand -base64 32)
TARA_SECRETS_VAULT_ADDR, TARA_SECRETS_VAULT_KEY, TARA_SECRETS_VAULT_TOKENA KMS instead: a Vault or OpenBao Transit key of type aes256-gcm96. All three are required together
TARA_SECRETS_VAULT_MOUNT, TARA_SECRETS_VAULT_NAMESPACEOptional. The Transit mount (default transit) and the namespace

Don't set TARA_SECRET_KEY together with the Vault variables. With neither, organizations can't configure SSO. Back the key up: if you lose it, saved secrets can't be read, and admins must enter them again. In production the issuer must be an https public address, and Tara refuses to connect to private or internal addresses. See Organization SSO.

Tokens for Ryoma and Bandum ​

Ryoma and Bandum read GitHub issues and PRs through a Tara service account, which asks Tara for short-lived read-only GitHub tokens.

VariableMeaning
RYOMA_TARA_SCM_TOKENThe Tara token Ryoma uses for this. If unset, Ryoma falls back to RYOMA_TARA_TOKEN
BANDUM_TARA_SCM_TOKENThe same for Bandum. If unset, it falls back to BANDUM_TARA_TOKEN

The service account's token needs the scm scope. Set it on the server (the account and token names are those of your install):

bash
tara-admin token-scopes ryoma-svc <token-name> read,scm
tara-admin token-scopes bandum-svc <token-name> read,delegate,scm

Leave the token unbound to an organization so it works for every organization with an installation, or bind it to one organization to limit it to that one.

Deprecated: RYOMA_SCM_SERVER_TOKEN_ORGS, BANDUM_SCM_SERVER_TOKEN_ORGS ​

These listed organizations that may use a single server-wide read-only token (RYOMA_SCM_TOKEN, BANDUM_SCM_TOKEN). They are empty by default now and are only a fallback for installs with one organization, or GitLab, which has no GitHub App. An organization with a GitHub App never uses them. Helm (Ryoma chart): config.scmServerTokenOrgs, default empty.

Further reading ​