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.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/orgs/{org}/gitlabGitLab 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Connection status | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
Example response
{
"enabled": false,
"hosts": [
{
"url": "string",
"oauth": false
}
],
"linked": false,
"host": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/gitlabSet 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
autoJoinRole | off | viewer | member | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Updated | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found or not connected | application/problem+json · object |
Example response
{
"enabled": false,
"hosts": [
{
"url": "string",
"oauth": false
}
],
"linked": false,
"host": "string"
}Call with curl
curl -X PATCH "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"autoJoinRole":"off"}'/v1/orgs/{org}/gitlabDisconnect 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 204 | Disconnected | |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found or not connected | application/problem+json · object |
Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/gitlab/connect/oauthStart 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
host | string | yes | One of the allowed hosts |
returnTo | string | Portal 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
| Code | Description | Type |
|---|---|---|
| 200 | Authorize URL | application/json · object |
| 400 | Host not allowed (host_not_allowed) or no OAuth app for it (oauth_not_configured) | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 409 | Already connected (org_already_linked) | application/problem+json · object |
Example response
{
"url": "string"
}Call with curl
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"}'/v1/orgs/{org}/gitlab/connect/tokenConnect 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
host | string | yes | |
token | string | yes | |
group | string | yes | Full path of the group |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Connected | application/json · object |
| 400 | Invalid token or group (token_invalid, token_scope, group_not_found, host_not_allowed) | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 409 | Already connected (org_already_linked) | application/problem+json · object |
| 502 | GitLab did not answer | application/problem+json · object |
Example response
{
"enabled": false,
"hosts": [
{
"url": "string",
"oauth": false
}
],
"linked": false,
"host": "string"
}Call with curl
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"}'/v1/orgs/{org}/gitlab/groupsPlaces 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Groups | application/json · object[] |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not connected | application/problem+json · object |
| 409 | Re-authorization needed (reauth_required) | application/problem+json · object |
| 502 | GitLab did not answer | application/problem+json · object |
Example response
[
{
"id": 0,
"canConnect": false,
"namespaceId": 0,
"fullPath": "string",
"name": "string",
"kind": "user"
}
]Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/groups" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/gitlab/groupChoose the group (or the own account) of an OAuth connection (owner or admin, session only)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
group | string | yes | Full path of a group from the list, or the user name of the connecting user's own account |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Group chosen | application/json · object |
| 400 | Group 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 |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not connected | application/problem+json · object |
| 502 | GitLab did not answer | application/problem+json · object |
Example response
{
"enabled": false,
"hosts": [
{
"url": "string",
"oauth": false
}
],
"linked": false,
"host": "string"
}Call with curl
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"}'/v1/orgs/{org}/gitlab/syncSync group members from GitLab now (owner or admin, session only)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Synced | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not connected | application/problem+json · object |
| 409 | Re-authorization needed (reauth_required) | application/problem+json · object |
| 502 | GitLab did not answer | application/problem+json · object |
Example response
{
"repos": 0,
"members": 0,
"joined": 0,
"removed": 0
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/sync" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/gitlab/webhookCreate 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | URL and new secret | application/json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not connected | application/problem+json · object |
Example response
{
"url": "string",
"secret": "string"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/webhook" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/gitlab/projectsRepositories of the connected group, including subgroups (cached about 10 minutes)
Callable by members. Used by the project repository picker.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
search | query | string |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Projects | application/json · object[] |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not connected | application/problem+json · object |
| 409 | Re-authorization needed (reauth_required) | application/problem+json · object |
| 502 | GitLab did not answer | application/problem+json · object |
Example response
[
{
"fullName": "string",
"private": false
}
]Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/gitlab/projects" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/scm/repoDoes 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
repo | query | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | The repository belongs to the organization | application/json · object |
| 400 | Invalid repository | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not in the organization | application/problem+json · object |
Example response
{
"provider": "github",
"fullName": "string",
"private": false,
"host": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/repo?repo=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/scm/tokenShort-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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
repo | query | string[] | yes | Repository path or URL; repeat the parameter for several |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Token | application/json · object |
| 400 | Invalid repository (or mixed providers | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden, or the repository is outside the connection (repo_not_in_installation, repo_not_in_group) | application/problem+json · object |
| 404 | No connection (github_not_linked, gitlab_not_connected) or project not found | application/problem+json · object |
| 409 | Suspended or re-authorization needed (reauth_required) | application/problem+json · object |
| 502 | GitLab did not answer | application/problem+json · object |
Example response
{
"provider": "github",
"host": "string",
"token": "string",
"expiresAt": "2026-11-01T00:00:00Z",
"repositories": [
"string"
]
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/token?repo=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/scm/release-approvalCan 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
project | query | string | Project key | |
repo | query | string | Repository path or URL | |
user | query | string | Tara login |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | The decision | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Organization or project not found | application/problem+json · object |
Example response
{
"allowed": false,
"reason": "owner",
"project": "string",
"role": "string"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/release-approval" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/scm/labelsDoes 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
repo | query | string | yes | owner/name |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Label status | application/json · object |
| 400 | Invalid repository | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Repository not in the installation (repo_not_in_installation), or no GitHub App (github_not_linked), or labels unavailable (labels_unavailable) | application/problem+json · object |
| 409 | The GitHub App installation is suspended (installation_suspended) | application/problem+json · object |
| 502 | GitHub did not answer | application/problem+json · object |
Example response
{
"repo": "string",
"ready": false,
"missing": [
"string"
],
"stale": [
"string"
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/scm/labels?repo=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/scm/labelsCreate 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repo | string | yes | owner/name for GitHub; a project URL or full path for GitLab |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | What changed | application/json · object |
| 400 | Invalid repository | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Not an owner or admin, not a session, or the app lacks Issues: write (issues_write_required) | application/problem+json · object |
| 404 | Repository not in the installation (repo_not_in_installation), or no GitHub App (github_not_linked) | application/problem+json · object |
| 409 | The GitHub App installation is suspended (installation_suspended) | application/problem+json · object |
| 502 | GitHub did not answer | application/problem+json · object |
Example response
{
"repo": "string",
"created": [
"string"
],
"updated": [
"string"
],
"unchanged": [
"string"
]
}Call with curl
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"}'