Skip to content

API Tara: scm ​

Source hosts of an organization beyond the GitHub App - GitLab connection, repository check and read tokens for both providers

This page is generated from openapi.yaml by npm run gen, so do not edit it by hand. Authentication is described on the overview page.

GET/v1/orgs/{org}/gitlab

GitLab connection of the organization (any member; the webhook and skipped list are for owners and admins)

enabled: false when this server cannot store secrets (set TARA_SECRET_KEY or TARA_SECRETS_VAULT_*). hosts lists the GitLab servers an owner or admin may connect (https://gitlab.com and the hosts of TARA_GITLAB_PROVIDERS); oauth says whether the server has an OAuth app for it (otherwise only a pasted token works). connection.status is pending_group after OAuth until a group is chosen, reauth_required when GitLab rejected the stored credential, otherwise ok.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Connection statusapplication/json · object
401Not signed inapplication/problem+json · object
404Not foundapplication/problem+json · object

Example response ​

json
{
  "enabled": false,
  "hosts": [
    {
      "url": "string",
      "oauth": false
    }
  ],
  "linked": false,
  "host": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab" \
  -H "Authorization: Bearer $TARA_TOKEN"
PATCH/v1/orgs/{org}/gitlab

Set the auto-join role (owner or admin, session only)

Same rules as GitHub (off, viewer or member; source gitlab_group; seat limits apply). A connection to an own account has no group, so turning it on is 400 auto_join_unavailable.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
autoJoinRoleoff | viewer | memberyes

Responses ​

CodeDescriptionType
200Updatedapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not found or not connectedapplication/problem+json · object

Example response ​

json
{
  "enabled": false,
  "hosts": [
    {
      "url": "string",
      "oauth": false
    }
  ],
  "linked": false,
  "host": "string"
}

Call with curl ​

bash
curl -X PATCH "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"autoJoinRole":"off"}'
DELETE/v1/orgs/{org}/gitlab

Disconnect GitLab (owner or admin, session only)

Deletes the stored credential. People who joined through the group become manual members. Revoke the token or OAuth grant on GitLab to fully revoke access.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
204Disconnected
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not found or not connectedapplication/problem+json · object

Call with curl ​

bash
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/gitlab/connect/oauth

Start the GitLab OAuth consent (owner or admin, session only)

Returns the GitLab authorize URL (Authorization Code + PKCE, scope read_api read_user) with a signed state bound to this organization and the caller (valid 15 minutes). GitLab redirects the browser to GET /auth/gitlab-connect/callback on this server (not part of this spec), which stores the tokens encrypted and sends the browser back to the Portal to choose a group.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
hoststringyesOne of the allowed hosts
returnTostringPortal page to send the browser back to after the callback; same rules and redirect query (?gitlab=<status> or ?gitlab_error=<code>) as returnTo of the GitHub install. Invalid: 400 invalid_return_to

Responses ​

CodeDescriptionType
200Authorize URLapplication/json · object
400Host not allowed (host_not_allowed) or no OAuth app for it (oauth_not_configured)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
409Already connected (org_already_linked)application/problem+json · object

Example response ​

json
{
  "url": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/connect/oauth" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host":"https://gitlab.com","returnTo":"/acme/setup?step=connect"}'
POST/v1/orgs/{org}/gitlab/connect/token

Connect GitLab with a pasted token and a group (owner or admin, session only)

The token is a Group Access Token, a Project Access Token or a bot user's personal access token with read_api. Tara validates the scopes (GET /personal_access_tokens/self) and that it can read the group, then stores it encrypted. It is never returned.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
hoststringyes
tokenstringyes
groupstringyesFull path of the group

Responses ​

CodeDescriptionType
200Connectedapplication/json · object
400Invalid token or group (token_invalid, token_scope, group_not_found, host_not_allowed)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
409Already connected (org_already_linked)application/problem+json · object
502GitLab did not answerapplication/problem+json · object

Example response ​

json
{
  "enabled": false,
  "hosts": [
    {
      "url": "string",
      "oauth": false
    }
  ],
  "linked": false,
  "host": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/connect/token" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host":"https://gitlab.com","token":"string","group":"my-group/sub"}'
GET/v1/orgs/{org}/gitlab/groups

Places the connected GitLab user can pick for the projects (owner or admin, session only)

The user's own account first (kind: user, the personal namespace), then the groups where the OAuth user is at least Maintainer (GET /groups?min_access_level=40, kind: group). projectCount is the number of projects when GitLab reports it (the X-Total header of a one-item page); it is absent when unknown, and only the first 20 places are counted (places that can be connected first). Groups where the user is a member below Maintainer follow, with canConnect: false. Only for a connection that uses OAuth.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Groupsapplication/json · object[]
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not connectedapplication/problem+json · object
409Re-authorization needed (reauth_required)application/problem+json · object
502GitLab did not answerapplication/problem+json · object

Example response ​

json
[
  {
    "id": 0,
    "canConnect": false,
    "namespaceId": 0,
    "fullPath": "string",
    "name": "string",
    "kind": "user"
  }
]

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/groups" \
  -H "Authorization: Bearer $TARA_TOKEN"
PUT/v1/orgs/{org}/gitlab/group

Choose the group (or the own account) of an OAuth connection (owner or admin, session only)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
groupstringyesFull path of a group from the list, or the user name of the connecting user's own account

Responses ​

CodeDescriptionType
200Group chosenapplication/json · object
400Group not found or a namespace of another user (group_not_found), or the user is below Maintainer in the group (group_access_too_low)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not connectedapplication/problem+json · object
502GitLab did not answerapplication/problem+json · object

Example response ​

json
{
  "enabled": false,
  "hosts": [
    {
      "url": "string",
      "oauth": false
    }
  ],
  "linked": false,
  "host": "string"
}

Call with curl ​

bash
curl -X PUT "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/group" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group":"string"}'
POST/v1/orgs/{org}/gitlab/sync

Sync group members from GitLab now (owner or admin, session only)

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200Syncedapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not connectedapplication/problem+json · object
409Re-authorization needed (reauth_required)application/problem+json · object
502GitLab did not answerapplication/problem+json · object

Example response ​

json
{
  "repos": 0,
  "members": 0,
  "joined": 0,
  "removed": 0
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/sync" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/gitlab/webhook

Create or rotate the webhook secret (owner or admin, session only)

Returns the webhook URL and a new secret, once; Tara keeps only a hash. Configure a GitLab group webhook (Premium or self-managed) or project webhooks with this URL and the secret as "Secret token", events: member and project events. Hourly sync works without webhooks.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Responses ​

CodeDescriptionType
200URL and new secretapplication/json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not connectedapplication/problem+json · object

Example response ​

json
{
  "url": "string",
  "secret": "string"
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/webhook" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/gitlab/projects

Repositories of the connected group, including subgroups (cached about 10 minutes)

Callable by members. Used by the project repository picker.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
searchquerystring

Responses ​

CodeDescriptionType
200Projectsapplication/json · object[]
401Not signed inapplication/problem+json · object
404Not connectedapplication/problem+json · object
409Re-authorization needed (reauth_required)application/problem+json · object
502GitLab did not answerapplication/problem+json · object

Example response ​

json
[
  {
    "fullName": "string",
    "private": false
  }
]

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/projects" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/scm/repo

Does this repository belong to the organization's GitHub App or GitLab group?

repo is a full path (owner/name, group/sub/name) or a URL (https://gitlab.com/group/name). The host of a URL picks the provider; a bare path is checked against the GitLab group first, then GitHub. 200 if it belongs, 404 if not or not connected.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
repoquerystringyes

Responses ​

CodeDescriptionType
200The repository belongs to the organizationapplication/json · object
400Invalid repositoryapplication/problem+json · object
401Not signed inapplication/problem+json · object
404Not in the organizationapplication/problem+json · object

Example response ​

json
{
  "provider": "github",
  "fullName": "string",
  "private": false,
  "host": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/repo?repo=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/scm/token

Short-lived read token for one or more repositories, GitHub or GitLab

Same callers as /github/token (service account with scope scm, or owner or admin from the Portal or CLI). repo is a full path or URL and can be repeated (1 to 100, all of one provider; mixing providers is a 400): the provider is picked as for GET /scm/repo, and one token covers all of them, so callers batch instead of asking per repository. GitHub: one installation token limited to those repositories (as /github/token). GitLab: GitLab tokens cannot be down-scoped, so Tara returns the stored (refreshed) credential, only if every repository path is inside the connected group and the project exists (otherwise the whole request is refused); expiresAt is at most one hour away and the caller must not persist the token. The token can read whatever the credential can read: use a Group Access Token for strict isolation. Each call is audit-logged (github.token or gitlab.token).

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
repoquerystring[]yesRepository path or URL; repeat the parameter for several

Responses ​

CodeDescriptionType
200Tokenapplication/json · object
400Invalid repository (or mixed providersapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbidden, or the repository is outside the connection (repo_not_in_installation, repo_not_in_group)application/problem+json · object
404No connection (github_not_linked, gitlab_not_connected) or project not foundapplication/problem+json · object
409Suspended or re-authorization needed (reauth_required)application/problem+json · object
502GitLab did not answerapplication/problem+json · object

Example response ​

json
{
  "provider": "github",
  "host": "string",
  "token": "string",
  "expiresAt": "2026-11-01T00:00:00Z",
  "repositories": [
    "string"
  ]
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/token?repo=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/scm/release-approval

Can this user approve releases of a project (or of the project that holds a repository)?

For Bandum, so it does not copy the role rules. Give exactly one of project (key) or repo (path or URL; the project is found from the repositories linked to projects). Callers: a service account with scope scm (bandum-svc; user is required), a delegation token (user is optional and can only be the token's own user) and any member (user optional, default the caller).

reason: owner (owner of the organization: always allowed), in_list (named in the project's release approvers), admin_no_list (an admin, and the project has no list), not_in_list (a member who is not allowed, including an admin when a list exists), not_member (no such member in this organization). A repository linked to no project follows the no-list rule (owner and admin only, project is null). A repository linked to several projects must be allowed by all of them. The answer is 200 in every case above; 404 only when the organization or the project does not exist. This tells only the platform part of section 4 of the release design; the Git permission of the approver's own token is checked by Bandum.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
projectquerystringProject key
repoquerystringRepository path or URL
userquerystringTara login

Responses ​

CodeDescriptionType
200The decisionapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Organization or project not foundapplication/problem+json · object

Example response ​

json
{
  "allowed": false,
  "reason": "owner",
  "project": "string",
  "role": "string"
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/release-approval" \
  -H "Authorization: Bearer $TARA_TOKEN"
GET/v1/orgs/{org}/scm/labels

Does this GitHub repository have the standard Bandum labels (`status: …`, `type: …`, `level: …`)?

Compares the repository's labels with the standard set (the same set ph bandum labels init creates). Callable by members and by a service account with scope scm (Ryoma uses it for the "missing labels" data warning). missing are standard labels the repository does not have; stale have the wrong color or description (fixed by POST). GitHub repositories of the organization's GitHub App installation only: 404 repo_not_in_installation or github_not_linked otherwise.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)
repoquerystringyesowner/name

Responses ​

CodeDescriptionType
200Label statusapplication/json · object
400Invalid repositoryapplication/problem+json · object
401Not signed inapplication/problem+json · object
404Repository not in the installation (repo_not_in_installation), or no GitHub App (github_not_linked), or labels unavailable (labels_unavailable)application/problem+json · object
409The GitHub App installation is suspended (installation_suspended)application/problem+json · object
502GitHub did not answerapplication/problem+json · object

Example response ​

json
{
  "repo": "string",
  "ready": false,
  "missing": [
    "string"
  ],
  "stale": [
    "string"
  ]
}

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/labels?repo=string" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/scm/labels

Create the standard labels on a repository, with the GitHub App or the GitLab connection (owner or admin, session only)

repo is owner/name or a GitHub URL for GitHub, and a full URL (https://gitlab.com/group/name) or path of a project inside the connected GitLab group or own account for GitLab. For GitLab only missing labels are created (updated is always empty; a label that already exists, also from a parent group, is left as it is); it needs the api scope (403 gitlab_write_required for a read-only pasted token).

GitHub: Creates the missing standard labels and fixes the color and description of existing ones; it never deletes or renames other labels, and running it again changes nothing. Uses the GitHub App's own permission, which must include Issues: write (403 issues_write_required if the installation has not accepted it yet; the owner of the GitHub account accepts the permission request on GitHub). Developers can do the same with their own GitHub token: ph bandum labels init.

Parameters ​

NameInTypeRequiredDescription
orgpathstringyesOrganization slug (the caller must be a member; otherwise 404)

Body (application/json) ​

FieldTypeRequiredDescription
repostringyesowner/name for GitHub; a project URL or full path for GitLab

Responses ​

CodeDescriptionType
200What changedapplication/json · object
400Invalid repositoryapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Not an owner or admin, not a session, or the app lacks Issues: write (issues_write_required)application/problem+json · object
404Repository not in the installation (repo_not_in_installation), or no GitHub App (github_not_linked)application/problem+json · object
409The GitHub App installation is suspended (installation_suspended)application/problem+json · object
502GitHub did not answerapplication/problem+json · object

Example response ​

json
{
  "repo": "string",
  "created": [
    "string"
  ],
  "updated": [
    "string"
  ],
  "unchanged": [
    "string"
  ]
}

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/labels" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo":"string"}'