API Tara: github
GitHub App connection of an organization (install, auto-join, repositories, read-only tokens)
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}/githubGitHub 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
| 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,
"linked": false,
"account": {
"login": "string",
"type": "Organization"
},
"repositorySelection": "all"
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/github" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/githubSet 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
| 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 (auto_join_needs_org) | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found or not linked | application/problem+json · object |
Example response
{
"enabled": false,
"linked": false,
"account": {
"login": "string",
"type": "Organization"
},
"repositorySelection": "all"
}Call with curl
curl -X PATCH "https://tara.phillipcli.cloud/v1/orgs/<org>/github" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"autoJoinRole":"off"}'/v1/orgs/{org}/githubUnlink 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
Responses
| Code | Description | Type |
|---|---|---|
| 204 | Unlinked | |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found or not linked | application/problem+json · object |
Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/orgs/<org>/github" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/github/installStart 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
| 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 |
|---|---|---|---|
returnTo | string | Portal 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
| Code | Description | Type |
|---|---|---|
| 200 | Install URL | application/json · object |
| 400 | Invalid returnTo (invalid_return_to) | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
| 409 | Already linked (org_already_linked) | application/problem+json · object |
| 503 | GitHub App is not configured on this server | application/problem+json · object |
Example response
{
"url": "string"
}Call with curl
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"}'/v1/orgs/{org}/github/syncSync repositories and members from GitHub 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 found or not linked | application/problem+json · object |
| 502 | GitHub 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>/github/sync" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/orgs/{org}/github/tokenShort-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
| 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 |
|---|---|---|---|
repositories | string[] | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Token | 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 linked (github_not_linked) | application/problem+json · object |
| 409 | Installation suspended (installation_suspended) | application/problem+json · object |
Example response
{
"token": "string",
"expiresAt": "2026-11-01T00:00:00Z",
"repositories": [
"string"
]
}Call with curl
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"]}'/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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
org | path | string | yes | Organization slug (the caller must be a member; otherwise 404) |
owner | path | string | yes | |
name | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | The repository is in the installation | application/json · object |
| 400 | Invalid repository name | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not in the installation | application/problem+json · object |
Example response
{
"fullName": "string",
"private": false
}Call with curl
curl "https://tara.phillipcli.cloud/v1/orgs/<org>/github/repos/<owner>/<name>" \
-H "Authorization: Bearer $TARA_TOKEN"