Skip to content

Connect GitLab ​

An Owner or Admin can connect one GitLab group to the PhillipCLI organization. It is the GitLab counterpart of the GitHub App, and it does the same three things:

  • Auto-join. Members of the group join your PhillipCLI organization when they sign in with GitLab, with the role you choose.
  • Repositories. A repository counts as yours only when it is inside the group, subgroups included. When you type a repository on a project, Tara checks it against the group and warns you if it is outside.
  • Issues and merge requests. Ryoma and Bandum read them with a short-lived credential that Tara hands out. Nobody pastes a personal token.

An organization has at most one GitLab connection, and it can have a GitHub App next to it.

Who can connect, and which hosts ​

You must be an Owner or Admin of the PhillipCLI organization and signed in to the Portal or the CLI. An API token can't change the connection.

The host is https://gitlab.com or a self-managed GitLab that the Tara operator has allowed. Any other host is refused with host_not_allowed. If you run a self-managed GitLab and the host is missing, ask the operator (developer site).

Two ways to give Tara access ​

OAuthPasted token
HowYou press Connect GitLab, say yes on GitLab, then pick where your projects are: your own account or a groupYou paste a Group Access Token, a Project Access Token, or a bot's personal access token, and type the group
NeedsThe operator registered an OAuth application for that hostNothing from the operator
Scopeapi (also lets Tara create labels)api (or read_api if Tara should only read)
If you leave the companyThe connection depends on your GitLab accountKeeps working

Recommended for strict isolation: a Group Access Token with the Reporter role. It is limited to the group, and it survives people leaving. A token with only read_api connects, but Tara then can't create the standard labels (gitlab_write_required). With OAuth you can pick your own account (projects you own) or a group where you are at least a Maintainer. With your own account there is no group, so teammates are invited by email instead of joining automatically.

What the credential can read

GitLab can't narrow a token to one repository, so the credential Tara hands to Bandum and Ryoma can read everything that the credential itself can read. Tara only hands it out for repositories inside the connected group. To keep the reach small, use a Group Access Token for that group.

Connect ​

  1. In Tara, open Settings › Source hosts (ph org gitlab connect in the terminal).
  2. Click Connect GitLab and allow access. The host list only shows when the server allows more than one GitLab. Administrators can instead open Other ways for administrators and paste a token with the group (or their own user name).
  3. Pick where your projects are. If only one place has projects, Tara picks it for you. With no project on GitLab yet, create one and press Check again.
  4. The page now shows the host, the group, the credential, and the auto-join setting.
Two ways in: the OAuth button, or paste a token together with the group path.
With OAuth, choose where your projects are after GitLab sends you back.
Connected: the host, the group, who connected it, and the auto-join setting.
bash
ph org gitlab                                   # status
ph org gitlab connect --host https://gitlab.com # OAuth in the browser, then choose the group
ph org gitlab connect --token-stdin --group acme/platform < token.txt
ph org gitlab group acme/platform               # choose the group of a waiting connection
ph org gitlab auto-join member                  # off, viewer, or member
ph org gitlab sync                              # reconcile members now
ph org gitlab webhook --rotate                  # create a webhook secret, shown once
ph org gitlab unlink --yes                      # disconnect

The token is read from standard input, never from the arguments, and Tara stores it encrypted. If the server has no encryption key configured, the page says GitLab can't be connected and the operator must set one.

Let people join on their own ​

SettingWhat happens
Off (default)Nobody joins automatically. You invite people.
ViewerGroup members join as Viewers, free and without a seat.
MemberThey join as Members and take a seat.

The rules are the same as for GitHub. Auto-join never gives Admin or Owner. When no seat is free (the Free plan has seven), sign-in still works and the person is listed as skipped. Someone who leaves the group is removed, but only if they joined this way. A person an Admin removed doesn't come back by themselves.

A person matches only if they sign in to Tara with GitLab on the same host as the connection. That needs a GitLab sign-in on the Tara server for that host (the operator sets it up with TARA_GITLAB_PROVIDERS; gitlab.com as a sign-in source is a separate entry from the connect-only one). Tara asks GitLab with the connection's credential whether that person is in the group. Every join and removal is in the audit log.

Webhook (optional) ​

Without a webhook, Tara still reconciles members and syncs knowledge sources every hour. A webhook only makes it react at once. Tara can't create hooks for you, so you add it by hand:

  1. In Tara, under Webhook, click Create or rotate secret. Copy the secret now, because it is shown once. The URL is shown on the same page.
  2. In GitLab, add a group webhook if your plan allows it (Premium, Ultimate, or a self-managed server). Otherwise add a webhook to each project.
  3. Paste the URL, put the secret in Secret token, and tick Member events, Project events, and Push events.
Copy the URL and the secret now, because the secret is shown only once.
  • Member events keep people in step with the group. They exist only on group webhooks.
  • Push events sync a knowledge source when the default branch changes.
  • Rotating the secret stops the old one from working at once.

Repositories, tasks, and merge requests in Ryoma and Bandum ​

Add the repositories to a project as full URLs, for example ph project edit <key> --add-repo https://gitlab.com/acme/platform/api. Ryoma reads a bare owner/repo as GitHub, so a GitLab repository needs its URL. Ryoma and Bandum then read them through the group credential. Only repositories inside the group work, and Tara refuses to hand out a credential for any other. It also checks that the repository exists. The credential is valid for at most an hour, can't be requested with a member's personal token, and every request is logged.

One request can cover many repositories of the group, so Bandum and Ryoma don't need a credential per repository.

When something goes wrong ​

CodeMeaning and what to do
host_not_allowedThe operator hasn't allowed that host.
oauth_not_configuredThe operator registered no OAuth application for that host. Paste a token instead.
token_invalidThe token is expired, lacks read_api or api, or can't see the group.
reauth_requiredGitLab rejected the credential (revoked, or the OAuth refresh failed). Disconnect and connect again.
repo_not_in_groupThe repository is outside the connected group.
org_already_linkedThe organization already has a GitLab connection. Disconnect it first.
bad_stateThe OAuth link expired (15 minutes) or belongs to someone else. Start again.

Further reading ​