GitHub App endpoints - installation status, linking an installation to an organisation, and listing repositories and branches.
GitHub
Private repositories are reached through a GitHub App installation, linked to a Light Cloud organisation. One GitHub account can be linked to several organisations, and one organisation can hold several installations.
These endpoints are mostly GET and take their parameters in the path or query string, unlike the rest of the API.
Check repository access#
/api/github-app/installation-statusWhether a specific repository is reachable. repoAccess: false with installed: true means the App is on the account but was not granted this repository.
- permission
- read:projects
Parameters
organisationIdstringrequired- Query parameter
ownerstringrequired- Query parameter — repository owner
repostringrequired- Query parameter — repository name
curl -G https://api.light-cloud.com/api/github-app/installation-status \
-H "Authorization: Bearer $SESSION_TOKEN" \
--data-urlencode "organisationId=org_1Ab" \
--data-urlencode "owner=acme" \
--data-urlencode "repo=shop"{
"configured": true,
"installed": true,
"installationId": 12345678,
"accountLogin": "acme",
"repoAccess": true
}Start an installation#
/api/github-app/installReturns the GitHub URL to send a person to. GitHub returns them to /api/github-app/callback, which links the installation.
- permission
- read:projects
curl https://api.light-cloud.com/api/github-app/install \
-H "Authorization: Bearer $SESSION_TOKEN"{ "url": "https://github.com/apps/light-cloud/installations/new?state=..." }List repositories#
/api/github-app/organisation/:orgId/repositoriesEvery repository the organisation's linked installations can reach.
- permission
- read:projects
Parameters
orgIdstringrequired- Path parameter — the organisation
curl https://api.light-cloud.com/api/github-app/organisation/org_1Ab/repositories \
-H "Authorization: Bearer $SESSION_TOKEN"[
{
"id": 45678901,
"name": "shop",
"full_name": "acme/shop",
"private": true,
"default_branch": "main"
}
]List branches#
/api/github-app/organisation/:orgId/repositories/:owner/:repo/branchesBranches of one repository. For a public repository you do not need an installation — use POST /api/applications/public-branches instead.
- permission
- read:projects
Parameters
orgIdstringrequired- Path parameter — the organisation
ownerstringrequired- Path parameter — repository owner
repostringrequired- Path parameter — repository name
curl https://api.light-cloud.com/api/github-app/organisation/org_1Ab/repositories/acme/shop/branches \
-H "Authorization: Bearer $SESSION_TOKEN"[
{ "name": "main", "commit_sha": "9f3c1ab" },
{ "name": "develop", "commit_sha": "2b8e004" }
]Check several accounts#
/api/github-app/organisation/:orgId/check-accountsWhich of these GitHub accounts have the App installed, and which are linked to this workspace. installed: true, linkedToThisOrg: false is the case that trips people up — the App is on that account, but this workspace cannot use it until it is linked.
- permission
- read:projects
Parameters
orgIdstringrequired- Path parameter — the organisation
accountLoginsstring[]required- GitHub account logins to check
curl -X POST https://api.light-cloud.com/api/github-app/organisation/org_1Ab/check-accounts \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountLogins": ["acme", "someone-else"]}'{
"accounts": {
"acme": { "installed": true, "linkedToThisOrg": true },
"someone-else": { "installed": true, "linkedToThisOrg": false }
}
}Managing installations#
| Endpoint | Description |
|---|---|
GET /api/github-app/installations | Every installation visible to the user |
GET /api/github-app/organisation/:orgId/installations | Those linked to this organisation |
POST /api/github-app/organisation/:orgId/link-installation | Attaches an existing installation to this organisation |
POST /api/github-app/organisation/:orgId/sync-installations | Re-reads GitHub and prunes rows whose installation is gone |
DELETE /api/github-app/organisation/:orgId/installations/:installId | Unlinks it from this organisation |
DELETE /api/github-app/organisation/:orgId/installations/:installId/uninstall | Unlinks and removes the App from the GitHub account |
GET /api/github-app/organisation/:organisationId/stream | Server-sent events, so a page can react as an installation completes |
GitLab and Bitbucket#
The same shape exists under /api/gitlab and /api/bitbucket (connections instead of installations: GET /organisation/:orgId/connections, POST /organisation/:orgId/link-connection, DELETE /organisation/:orgId/connections/:id, POST /disconnect, and the same repository and branch listings), each behind a feature flag. Check GET /api/config/feature-flags before relying on them.