Skip to content

API Tara: github ​

GitHub App connection of an organization (install, auto-join, repositories, read-only tokens)

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}/github

GitHub App connection of the organization (any member; the skipped list is for owners and admins)

enabled: false when this Tara server has no GitHub App configured (TARA_GITHUB_APP_*). linked: false until an owner or admin connects an installation. A repository belongs to the organization if and only if it is in the installation.

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,
  "linked": false,
  "account": {
    "login": "string",
    "type": "Organization"
  },
  "repositorySelection": "all"
}

Call with curl ​

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

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

autoJoinRole is off, viewer or member, never admin or owner. Members of the GitHub organization that owns the installation join the Tara organization with this role when they sign in with GitHub (source github_app); the periodic sync removes only people who joined this way and have left the GitHub organization. Needs the installation to be on a GitHub organization, not a personal account.

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 input (auto_join_needs_org)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not found or not linkedapplication/problem+json · object

Example response ​

json
{
  "enabled": false,
  "linked": false,
  "account": {
    "login": "string",
    "type": "Organization"
  },
  "repositorySelection": "all"
}

Call with curl ​

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

Unlink the GitHub installation (owner or admin, session only)

People who joined through the GitHub App become manual members. The app stays installed on GitHub; uninstall it there to revoke access.

Parameters ​

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

Responses ​

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

Call with curl ​

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

Start installing the GitHub App (owner or admin, session only)

Returns the GitHub URL to open. It carries a signed state bound to this organization and the caller (valid 15 minutes). GitHub then redirects the browser to GET /auth/github-app/setup?installation_id=&setup_action=&code=&state= on this server (not part of this spec), which verifies the state, that the caller is still an owner or admin, that the caller's own GitHub token sees the installation and owns the GitHub account, and that the installation is not linked elsewhere, before linking it.

The optional body returnTo sends the browser back to a Portal page afterwards (the setup wizard uses /<org>/setup?step=connect). It must be a relative path that starts with /<org>/ of this organization (no //, no scheme, no backslash, no .., no fragment, at most 512 characters); anything else is refused with 400 invalid_return_to. It travels inside the signed state, and the callback redirects to it with ?github=connected or ?github_error=<code> (& when returnTo already has a query). Without returnTo the browser goes to /<org>/settings/github as before.

Parameters ​

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

Body (application/json) ​

FieldTypeRequiredDescription
returnTostringPortal page to send the browser back to after the callback. A relative path that starts with /<org>/ of this organization (no //, scheme, backslash, .. or fragment; at most 512 characters)

Responses ​

CodeDescriptionType
200Install URLapplication/json · object
400Invalid returnTo (invalid_return_to)application/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not foundapplication/problem+json · object
409Already linked (org_already_linked)application/problem+json · object
503GitHub App is not configured on this serverapplication/problem+json · object

Example response ​

json
{
  "url": "string"
}

Call with curl ​

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

Sync repositories and members from GitHub 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 found or not linkedapplication/problem+json · object
502GitHub 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>/github/sync" \
  -H "Authorization: Bearer $TARA_TOKEN"
POST/v1/orgs/{org}/github/token

Short-lived read-only GitHub token for repositories of the installation

For a service account with scope scm (Ryoma, Bandum; granted with tara-admin token-scopes), or an owner or admin signed in to the Portal or CLI. Delegation tokens and personal API tokens cannot call it, because the app token reads repositories the person may not see on GitHub. Every repository must be in this organization's installation (403 repo_not_in_installation); the token is limited to them and to read access to contents, issues, pull requests and metadata, and lives about one hour. Each call is audit-logged.

Parameters ​

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

Body (application/json) ​

FieldTypeRequiredDescription
repositoriesstring[]yes

Responses ​

CodeDescriptionType
200Tokenapplication/json · object
400Invalid inputapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Forbiddenapplication/problem+json · object
404Not found or not linked (github_not_linked)application/problem+json · object
409Installation suspended (installation_suspended)application/problem+json · object

Example response ​

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

Call with curl ​

bash
curl -X POST "https://tara.phillipcli.cloud/v1/orgs/<org>/github/token" \
  -H "Authorization: Bearer $TARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repositories":["string"]}'
GET/v1/orgs/{org}/github/repos/{owner}/{name}

Does this repository belong to the organization? (200 if it is in the installation, 404 if not)

Callable by members (including through a delegation token) and by a service account with scope scm.

Parameters ​

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

Responses ​

CodeDescriptionType
200The repository is in the installationapplication/json · object
400Invalid repository nameapplication/problem+json · object
401Not signed inapplication/problem+json · object
404Not in the installationapplication/problem+json · object

Example response ​

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

Call with curl ​

bash
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/github/repos/<owner>/<name>" \
  -H "Authorization: Bearer $TARA_TOKEN"