Prepare GitHub and GitLab
This page is for the administrator of your company's GitHub organization or GitLab group. You do it once, before you invite anyone to an PhillipCLI organization. After you finish the steps below, people can sign in to Tara with their GitHub or GitLab accounts, Phillip connects with one click on Authorize, and Bandum and Ryoma can read the project's issues and PRs.
On the shared PhillipCLI service
On the shared service (tara.phillipcli.cloud), anyone with a GitHub account can sign in, and the platform's own OAuth app is already registered. You don't register a Tara sign-in app yourself. Signing in only says who you are. You join an organization through an invitation, from the Portal or with ph org invite. Your GitHub organization's members can join on their own through the GitHub App (Connect GitHub), and your organization can set up its own SSO in the Portal (Organization SSO). The steps for the Tara sign-in app below are for self-hosted installs. To register the GitHub App on a self-hosted install, see Register the GitHub App.
The GitLab screenshots on this page were taken on GitLab Community Edition 18.11. Other versions may place buttons slightly differently, but the item names stay the same.
| Task | GitHub | GitLab | Who does it |
|---|---|---|---|
| Where people and repos live | Organization | Group | Owner |
| Tara sign-in | OAuth app Tara | The group's Tara application | Organization or group owner |
| Phillip connects without pasting a token | OAuth app Phillip | The group's Phillip application | Organization or group owner |
| Bandum and Ryoma read data | Read-only fine-grained token | Group access token read_api | Owner |
| Ryoma syncs as soon as something changes (optional) | Repo webhook | Project webhook | Maintainer or higher |
Organization and members
GitHub
If you don't have an organization yet, go to your avatar › Your organizations › New organization and choose the Free plan. Choose a stable name from the start.
To invite members, go to the organization page › People › Invite member, type the GitHub account name or email, and click Invite. The invitee must accept the invitation before they can see the organization's repos.
GitLab
Use one group for the people who should join your PhillipCLI organization. Tara maps a group to an organization role by the group's full path, for example acme or acme/dev. Create the group at Groups › New group › Create group, enter a name, and choose Private.
To add people, go to the group › Manage › Members › Invite members, choose the account and role, and click Invite. Dev and Test need the Developer role or higher to open merge requests. A BA who only needs to read and test can have Reporter.
OAuth app for Tara sign-in
GitHub
- Go to the organization page › Settings › Developer settings › OAuth Apps › New OAuth app. Create the app under the organization, not under a personal account, so the app doesn't depend on one person.
- Set Application name to
Tara, Homepage URL to the Tara address, and Redirect URI to<Tara address>/auth/github/callback. Don't select Enable Device Flow. - Click Register application, then click Generate a new client secret on the page that opens. The secret appears only once, so copy it right away.
Tara requests two permissions, read:user and user:email, only to read the profile. It doesn't request read:org and doesn't check organization membership, so GitHub sign-in only says who the person is. Set these variables for Tara:
TARA_GITHUB_CLIENT_ID=<Client ID>
TARA_GITHUB_CLIENT_SECRET=<Client secret>On a self-hosted single-organization install, you can also set TARA_GITHUB_ORG so members of that GitHub organization join the organization automatically (see Self-hosted, single organization). That is the only use of this variable, and only then does Tara also request read:org, to read membership. If the GitHub organization turns on the Third-party application access policy in restricted mode, an owner must approve an outsider's OAuth app before it can read organization data. An app owned by the organization itself isn't blocked, which is why step 1 creates the app under the organization. View the policy at Settings › Third-party access › OAuth application policy.
GitLab
You don't need admin rights on the whole GitLab server. A group owner can create the application right in the group.
- Go to the group › Settings › Applications › Add new application.
- Set Name to
Taraand Redirect URI to<Tara address>/auth/gitlab/<id>/callback.<id>is the identifier you choose for this GitLab server in the Tara configuration, for exampleacme. - Keep Confidential selected and don't select Device authorization grant. Under Scopes, select
openid,profile,email, andapi. Theapiscope lets the same application connect an organization's GitLab with one click (see below); without it, connecting needs a pasted token. - Click Save application. The result page shows the Application ID and the Secret. The full secret appears only now, so copy it right away.
Each GitLab server is one element of TARA_GITLAB_PROVIDERS. Pass the secret through a separate variable:
export TARA_GITLAB_ACME_SECRET=<Secret>
export TARA_GITLAB_PROVIDERS='[
{ "id": "acme", "name": "GitLab Acme", "url": "https://gitlab.example.com",
"clientId": "<Application ID>", "clientSecretEnv": "TARA_GITLAB_ACME_SECRET",
"groups": { "acme": "member", "acme/admins": "admin", "acme/guests": "viewer" } }
]'The groups section maps a group's full path to an organization role: admin, member, or viewer. owner can't be granted by a group. If a user belongs to several listed groups, the highest role wins. The role goes into the single organization of a self-hosted install (TARA_SINGLE_ORG). A user who belongs to none of the listed groups sees a message asking their team lead to add them to a group. Tara reports an error at startup if a value isn't a valid role. Leave groups out to let any account on that GitLab sign in, as with GitHub; nobody then joins an organization automatically.
Connect a GitLab group to an organization
Besides signing in, an organization's Owner or Admin can connect a GitLab group with OAuth. For that, add an element to TARA_GITLAB_PROVIDERS with "connectOnly": true. It is used only to connect organizations, not as a sign-in button, and its groups may be empty:
export TARA_GITLAB_COM_SECRET=<Secret>
export TARA_GITLAB_PROVIDERS='[
{ "id": "gitlab-com", "name": "GitLab.com", "url": "https://gitlab.com", "connectOnly": true,
"clientId": "<Application ID>", "clientSecretEnv": "TARA_GITLAB_COM_SECRET" }
]'Register the OAuth application on that GitLab (Settings › Applications of a group or your account) with these values:
- Redirect URI:
<TARA_PUBLIC_URL>/auth/gitlab-connect/callback, for examplehttps://tara.example.com/auth/gitlab-connect/callback. This is a different address from the sign-in callback above. - Confidential: selected.
- Scopes:
api(it covers reading and creating labels, so the connect button needs nothing else). The application that also handles sign-in needsopenid profile email api. - Second redirect URI (one-click Connect GitLab in Bandum):
<TARA_PUBLIC_URL>/auth/scm-user/callback, on its own line in the same application.
This works the same for gitlab.com and for a self-managed GitLab: use that server's url. Tara allows https://gitlab.com and the url of every element in TARA_GITLAB_PROVIDERS as connection hosts, and refuses any other host. A host with no OAuth application can still be connected by pasting a Group Access Token. Tara stores credentials encrypted, so set TARA_SECRET_KEY or TARA_SECRETS_VAULT_*; without one, the connection page reports that GitLab can't be connected. To also let people sign in with the same host, add a second element for it without connectOnly.
Bandum and Ryoma read GitLab repositories with the credential Tara hands out, using the kit-scm-gitlab kit next to the GitHub one. Set BANDUM_SCM_GITLAB_PLUGIN (with BANDUM_SCM_GITLAB_PLUGIN_SHA256, or BANDUM_SCM_GITLAB_PLUGIN_DIR for a local copy) and RYOMA_SCM_GITLAB_PLUGIN (name@version:sha256). Ryoma needs RYOMA_SCM_PLUGIN and RYOMA_TARA_SCM_TOKEN too. In the Ryoma Helm chart the plugin is the value config.scmGitlabPlugin, and the single-host compose reads the same variables from its env file. Each repository is read from the host of the organization's connection, so several organizations can use GitHub, gitlab.com, and a self-managed GitLab at once. Without the GitLab kit, GitLab repositories aren't read.
After you restart Tara, the sign-in page has an extra button with the name you set in name. The first time a user clicks it, GitLab asks whether to let Tara read their profile.
OAuth app for Phillip
With this app, ph connect opens the browser so the user clicks Authorize instead of creating a token themselves. This is a public app with no secret, because it runs on each person's machine.
GitHub
Create one more OAuth app under the organization as above, with Application name Phillip, Redirect URI http://127.0.0.1:7171/callback, and Enable Device Flow selected. Device flow lets a user on a machine that can't open a browser enter a code at github.com/login/device. This app doesn't need a client secret.
GitLab
In the group › Settings › Applications, create an application Phillip with Redirect URI http://127.0.0.1:7171/callback, clear Confidential, and select only the scope api.
Device flow on GitLab 18 is off by default (feature flag oauth2_device_grant_flow). So for GitLab, set deviceFlow to false, and Phillip opens the browser instead of showing a code.
Declare both apps to Tara so Tara can relay them to Phillip:
TARA_SCM_OAUTH_CLIENTS='[
{ "host": "github.com", "kind": "github", "clientId": "<Client ID of the Phillip app>", "deviceFlow": true, "scopes": ["repo"] },
{ "host": "gitlab.example.com", "kind": "gitlab", "clientId": "<Application ID of the Phillip app>", "deviceFlow": false,
"redirectPort": 7171, "scopes": ["api"] },
{ "host": "localhost:8929", "scheme": "http", "kind": "gitlab", "clientId": "<Application ID of the Phillip app>",
"redirectPort": 7171, "scopes": ["api"] }
]'host is the host name, with :port only when the server is not on the default port (like localhost:8929), and with no https:// or path. scheme is optional (http or https, default https); set "scheme": "http" for a self-hosted server without TLS. This is a public app, so the JSON must not contain a secret. If it does, Tara reports an error at startup.
Service tokens for Bandum and Ryoma
Online Bandum and Ryoma read issues, PRs, and test files with a read-only token for the organization, not any person's token. Manual test results are still recorded under the name of the person who clicked, using their own token.
GitHub
Use a service account that is a member of the organization. Go to Settings › Developer settings › Personal access tokens › Fine-grained tokens › Generate new token. Set Resource owner to the organization and choose Only select repositories with the project repos.
Under Permissions, click Add permissions and add Contents, Issues, and Pull requests. For a service token, set all three to Read-only. Metadata is always Read-only and you can't remove it. The image below is a Dev's personal token, so it is set to Read and write.
If the organization requires approval of fine-grained tokens, the token works only after an owner approves it at Settings › Personal access tokens › Pending requests.
GitLab
Use a group access token, which needs no service account. Go to the group › Settings › Access tokens › Add new token, enter a name such as bandum-ryoma-doc, choose an expiration date and the Reporter role, and select only read_api.
A token lasts at most one year. Set a calendar reminder to issue a new token before it expires, because when it expires, Bandum and Ryoma stop syncing.
Put the token in the service configuration:
BANDUM_SCM_PLUGIN=kit-scm-gitlab@<version> BANDUM_SCM_PLUGIN_SHA256=<sha256> BANDUM_SCM_TOKEN=<token>
RYOMA_SCM_PLUGIN=kit-scm-gitlab@<version>:<sha256> RYOMA_SCM_TOKEN=<token>For a self-hosted GitLab, add BANDUM_SCM_SETTINGS and RYOMA_SCM_SETTINGS set to {"apiUrl":"https://gitlab.example.com/api/v4","webUrl":"https://gitlab.example.com"}, because the default kit calls gitlab.com. apiUrl is the API address the service calls. webUrl is the web address, which Bandum uses for the Create token link so users open the token creation page on your server. If you forget webUrl, the link still points to gitlab.com, and Bandum logs a warning at startup. On a personal machine that uses Phillip, set PHILLIP_GITLAB_URL (and PHILLIP_GITLAB_API if needed) for the same purpose; GitHub Enterprise has PHILLIP_GITHUB_URL. Get the kit's version and sha256 on the resource page on Tara.
Webhook for Ryoma
Without a webhook, Ryoma still syncs on a schedule (every 5 minutes by default). A webhook only makes the numbers update almost immediately. Ryoma doesn't read the webhook content. It only marks the repo as needing a sync, then reads again through the service token.
Set a shared secret with RYOMA_WEBHOOK_SECRET (for example, generate one with openssl rand -hex 32), then create a webhook with the URL <Ryoma address>/webhooks/scm?repo=<repo URL>.
On GitHub, go to the repo › Settings › Webhooks › Add webhook. Set Content type to application/json, paste the secret into Secret, choose Let me select individual events, and select Issues and Pull requests. GitHub signs the payload with that secret, and Ryoma verifies the signature.
On GitLab, go to the project › Settings › Webhooks › Add new webhook. Paste the secret into Secret token, and select Work item events (formerly called Issues events) and Merge request events.
Verify
- Open the Tara sign-in page and confirm it shows every configured GitHub or GitLab button. Sign in with a member account. On the shared service or a multi-organization install, a person with no organization sees the Get started screen. On a GitLab or SSO install, an account outside the mapped groups is blocked with a message.
- On a Dev machine, run
ph connectin the project repo. The browser opens the Authorize screen and doesn't ask you to paste a token. - In Bandum, click Sync now on the Board and confirm the current sprint's issues appear.
- Change a label on an issue and watch Ryoma update within a few seconds if you turned on the webhook.
Members do their own part by following Connect GitHub or GitLab.