#GitHub

---

#GET /github/install-callback

GitHub App install callback

Public redirect target from GitHub. Authenticated by the signed state JWT in the ?state query param, verified in-handler — no session or Bearer token. Persists the installation and 302-redirects to project settings.

Auth: Bearer token required

Query parameters

Name	Type	Description
installation_id	integer	GitHub installation ID (required)
setup_action	install | update	GitHub sends install on first install and update on re-installs, repo-selection changes and permission updates (required)
state	string	Signed install-state JWT minted by install-url (required)

Responses

Status	Description	Schema
302	Status 302	object
400	Bad Request	Error
404	Not Found	Error
409	Conflict	Error
503	Service Unavailable	Error

---

#POST /github/installations/recover

Recover an unclaimed GitHub installation

Org owner/admin only (checked in-handler via resolveOrgRoleForUser — no org segment in the path for a derived floor, see spec §15.4). Claims an installation that exists on GitHub but has no Terrantula row.

Auth: Bearer token required

Request body (application/json)

Field	Type	Description
orgId	string	Organization id or slug (required)
installationId	integer	GitHub installation ID (from the GitHub install URL) (required)

Responses

Status	Description	Schema
200	OK	RecoveredGitHubInstallation
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
409	Conflict	Error
503	Service Unavailable	Error

---

#GET /github/installations

List GitHub installations for an org

Org member only (checked in-handler via resolveOrgRoleForUser, see spec §15.4). ?orgId is required.

Auth: Bearer token required

Query parameters

Name	Type	Description
orgId	string	Organization id or slug (required)

Responses

Status	Description	Schema
200	OK	GitHubInstallationList
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
503	Service Unavailable	Error

---

#GET /github/installations/{installationId}/repos

List an installation's granted repos

Org member only (checked in-handler via resolveOrgRoleForUser, see spec §15.4). Returns the cached granted_repos for the installation.

Auth: Bearer token required

Path parameters

Name	Type	Description
installationId	string	Installation row ID

Responses

Status	Description	Schema
200	OK	GitHubGrantedRepoList
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
503	Service Unavailable	Error

---

#DELETE /github/installations/{installationId}

Soft-delete a GitHub installation

Org owner/admin only (checked in-handler via resolveOrgRoleForUser, see spec §15.4). Marks the installation deleted in Terrantula; does not uninstall on GitHub.

Auth: Bearer token required

Path parameters

Name	Type	Description
installationId	string	Installation row ID

Responses

Status	Description	Schema
200	OK	object
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
503	Service Unavailable	Error

---

#POST /{o}/{p}/github/install-url

Get a GitHub App install URL

Returns a GitHub installation URL carrying a signed state JWT for this project.

Auth: Bearer token required · Permission: tokens:manage

Path parameters

Name	Type	Description
o	string
p	string

Responses

Status	Description	Schema
200	OK	GitHubInstallUrl
401	Unauthorized	Error
403	Forbidden	Error
503	Service Unavailable	Error

---

#GET /orgs/{orgId}/projects/{projectId}/github-repos

List project ↔ GitHub repo links

Read-only.

Auth: Bearer token required · Permission: catalog:read

Path parameters

Name	Type	Description
orgId	string	Organization slug
projectId	string	Project name

Responses

Status	Description	Schema
200	OK	ProjectGithubRepoLinkList
401	Unauthorized	Error
403	Forbidden	Error

---

#POST /orgs/{orgId}/projects/{projectId}/github-repos

Link a GitHub repo to the project

Requires tokens:manage. Validates the installation belongs to the org and the repo is granted; resolves the repo node id server-side.

Auth: Bearer token required · Permission: tokens:manage

Path parameters

Name	Type	Description
orgId	string	Organization slug
projectId	string	Project name

Request body (application/json)

Field	Type	Description
installationId	string(uuid)	(required)
repoFullName	string	(required)

Responses

Status	Description	Schema
201	Created	ProjectGithubRepoLink
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
409	Conflict	Error

---

#DELETE /orgs/{orgId}/projects/{projectId}/github-repos/{id}

Unlink a GitHub repo from the project

Requires tokens:manage.

Auth: Bearer token required · Permission: tokens:manage

Path parameters

Name	Type	Description
orgId	string	Organization slug
projectId	string	Project name
id	string(uuid)	project_github_repos.id (UUID) — returned by linkRepo

Responses

Status	Description	Schema
200	OK	DeletedById
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

#Schemas

#DeletedById

Field	Type	Description
deleted	true	(required)
id	string	(required)

#Error

Field	Type	Description
error	string	(required)
code	string

#GitHubGrantedRepoList

Type: object[]

#GitHubInstallUrl

Field	Type	Description
url	string	(required)

#GitHubInstallation

Field	Type	Description
id	string(uuid)	(required)
githubInstallationId	integer	(required)
githubOrgLogin	string	(required)
status	string	(required)
installedAt	string | string	(required)
updatedAt	string | string	(required)

#GitHubInstallationList

Type: GitHubInstallation[]

#ProjectGithubRepoLink

Field	Type	Description
id	string(uuid)	(required)
installationId	string(uuid)	(required)
repoFullName	string	(required)
repoNodeId	string	(required)
linkedAt	string | string	(required)
linkedBy	string | null	(required)

#ProjectGithubRepoLinkList

Type: ProjectGithubRepoLink[]

#RecoveredGitHubInstallation

Field	Type	Description
id	string(uuid)	(required)
githubInstallationId	integer	(required)
githubOrgLogin	string	(required)