Skip to content

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.

TaskGitHubGitLabWho does it
Where people and repos liveOrganizationGroupOwner
Tara sign-inOAuth app TaraThe group's Tara applicationOrganization or group owner
Phillip connects without pasting a tokenOAuth app PhillipThe group's Phillip applicationOrganization or group owner
Bandum and Ryoma read dataRead-only fine-grained tokenGroup access token read_apiOwner
Ryoma syncs as soon as something changes (optional)Repo webhookProject webhookMaintainer 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.

Invite a member to the GitHub organization. They see the organization's repos only after they accept the invitation.

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.

The path in the Group URL field is the value you declare in the group-to-role mapping.

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.

Add members to the group, and choose the Developer role for Dev and Test.

OAuth app for Tara sign-in ​

GitHub ​

  1. 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.
  2. 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.
  3. 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.
The Redirect URI must match the Tara address plus /auth/github/callback character for character.

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:

bash
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.

When the policy is Access restricted, only the organization's own apps and approved apps can read organization data.

GitLab ​

You don't need admin rights on the whole GitLab server. A group owner can create the application right in the group.

  1. Go to the group › Settings › Applications › Add new application.
  2. Set Name to Tara and Redirect URI to <Tara address>/auth/gitlab/<id>/callback. <id> is the identifier you choose for this GitLab server in the Tara configuration, for example acme.
  3. Keep Confidential selected and don't select Device authorization grant. Under Scopes, select openid, profile, email, and api. The api scope lets the same application connect an organization's GitLab with one click (see below); without it, connecting needs a pasted token.
  4. Click Save application. The result page shows the Application ID and the Secret. The full secret appears only now, so copy it right away.
The three scopes openid, profile, and email are enough: GitLab returns the list of groups in the user info.
Copy the Application ID and Secret right away. If you lose the secret, click Renew secret to issue a new one.

Each GitLab server is one element of TARA_GITLAB_PROVIDERS. Pass the secret through a separate variable:

bash
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:

bash
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 example https://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 needs openid 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.

Each configured GitLab server is a separate button on the sign-in page.
Users see this screen only the first time. Tara reads only the profile and the list of groups.

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.

The app for Phillip uses a loopback address on the user's machine and turns on Device Flow.

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.

Clear Confidential because Phillip runs on the user's machine and holds no secret.

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:

bash
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.

Choose the organization as Resource owner, then select only 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.

A service token keeps all three permissions Read-only. A Dev's token is set to Read and write, as in the image.

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.

The Reporter role and the read_api scope are enough for Bandum and Ryoma to read issues, merge requests, and files.

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:

bash
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.

GitHub webhook: choose Let me select individual events, and select Issues and Pull requests.

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.

GitLab webhook: select Work item events and Merge request events.

Verify ​

  1. 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.
  2. On a Dev machine, run ph connect in the project repo. The browser opens the Authorize screen and doesn't ask you to paste a token.
  3. In Bandum, click Sync now on the Board and confirm the current sprint's issues appear.
  4. 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.