#GitHub

---

#POST /github/install-url

Get a GitHub App install URL

Session-authed. Returns a GitHub installation URL carrying a signed state JWT for the caller's project.

Auth: Bearer token required

Request body (application/json)

Field	Type	Description
projectId	string	(required)

Responses

Status	Description	Schema
200	Install URL	GitHubInstallUrl
401	Unauthorized	Error
403	Not a project member	Error
503	GitHub App not configured	Error

---

#GET /github/install-callback

GitHub App install callback

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

Auth: Bearer token required

Responses

Status	Description	Schema
302	Redirect to project settings
400	Missing/invalid params or state	Error
404	Project no longer exists	Error
409	Installation claimed by another tenant	Error
503	GitHub App not configured	Error

---

#POST /github/installations/recover

Recover an unclaimed GitHub installation

Session-authed (org owner/admin). 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	(required)
installationId	integer	(required)

Responses

Status	Description	Schema
200	Claimed installation	object
401	Unauthorized	Error
403	Forbidden (member role)	Error
404	Installation not found on GitHub	Error
409	Installation already claimed	Error
503	GitHub App not configured	Error

---

#GET /github/installations

List GitHub installations for an org

Session-authed (org member). ?orgId is required.

Auth: Bearer token required

Responses

Status	Description	Schema
200	Active installations	GitHubInstallationList
400	orgId required	Error
401	Unauthorized	Error
403	Not an org member	Error
503	GitHub App not configured	Error

---

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

List an installation's granted repos

Session-authed (org member). Returns the cached granted_repos for the installation.

Auth: Bearer token required

Path parameters

Name	Type	Description
installationId	string

Responses

Status	Description	Schema
200	Granted repos	GitHubGrantedRepoList
401	Unauthorized	Error
403	Not an org member	Error
404	Installation not found	Error
503	GitHub App not configured	Error

---

#DELETE /github/installations/{installationId}

Soft-delete a GitHub installation

Session-authed (org owner/admin). Marks the installation deleted in Terrantula; does not uninstall on GitHub.

Auth: Bearer token required

Path parameters

Name	Type	Description
installationId	string

Responses

Status	Description	Schema
200	Deleted	object
401	Unauthorized	Error
403	Forbidden (member role)	Error
404	Installation not found	Error
503	GitHub App not configured	Error

---

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

List project ↔ GitHub repo links

Read-only; gated by project membership (no extra permission).

Auth: Bearer token required

Path parameters

Name	Type	Description
orgId	string
projectId	string

Responses

Status	Description	Schema
200	Repo links	ProjectGithubRepoLinkList

---

#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
projectId	string

Request body (application/json)

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

Responses

Status	Description	Schema
201	Created link	ProjectGithubRepoLink
400	Installation not active	Error
404	Repo not found or not granted	Error
409	Repo already linked	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
projectId	string
id	string

Responses

Status	Description	Schema
200	Deleted link	object
404	Link not found	Error

#Schemas

#Error

Field	Type	Description
error	string	(required)
code	string

#GitHubGrantedRepoList

Type: object[]

#GitHubInstallUrl

Field	Type	Description
url	string	(required)

#GitHubInstallationList

Type: object[]

#ProjectGithubRepoLink

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

#ProjectGithubRepoLinkList

Type: ProjectGithubRepoLink[]