GitHub API

The GitHub API connects an Alaf Server instance to GitHub — via the Alaf Server GitHub App, an OAuth account, or the local gh CLI — and then lets you browse the accounts, repositories, branches and files you can deploy from. It also manages the push webhooks that drive auto-deploy. In the dashboard this is the GitHub connection card in Settings and the repo picker in the deploy wizard.

Endpoints

Connection state

GET /api/github/home is the dashboard's single entry point: it returns { state, accounts, repos } in one round trip, filtered to the accounts and repos your member role is allowed to see. GET /api/github/status is narrower — the Settings card's data source — returning { state, accounts, installUrl, cloudUnreachable }.

curl https://your-host/api/github/home \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN"

# The CLI has no dedicated `github` command; use the raw-request escape hatch:
alaf server api /github/home

Connect

Starts or advances the connection flow. The response is intentionally mode-agnostic — the frontend just reacts to the flow field:

• { connected: true } — already connected, nothing to do.
• { connected: false, flow: "redirect", url } — open url (OAuth handoff or GitHub App install).
• { connected: false, flow: "device_code", userCode, verificationUri, ... } — self-hosted device login.
• { connected: false, flow: "terminal", command, message } — run command (e.g. gh auth login) yourself.

POST /api/github/connect

The optional body field source ("oauth" | "cli") forces a specific path when the dashboard shows both the "Connect Alaf Server App" and "Use gh CLI" buttons; omit it to let the server pick based on the instance's auth mode.

curl -X POST https://your-host/api/github/connect \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"oauth"}'

Disconnect

POST /api/github/disconnect

Body (or ?source=): source is "oauth", "cli", or "all" (default "all"). This drops Alaf Server's stored credentials for that source; it does not uninstall the GitHub App — that happens only when you remove it from github.com (Alaf Server reacts to the uninstall webhook).

alaf server api /github/disconnect -X POST -d '{"source":"cli"}'

Create a repository

POST /api/github/repos

curl -X POST https://your-host/api/github/repos \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app","private":true,"owner":"acme"}'

alaf server api /github/repos -X POST -d '{"name":"my-app","private":true}'

Returns 201 with { data } (the created repository).

Browse repos, branches and files

List repos for the connected account (?owner= narrows to one account), or for a named org via GET /api/github/orgs/:org/repos. Both return { data: [...] } filtered to repos your role may see.

# Repos for one owner
alaf server api /github/repos --query owner=acme

# Branches for a repo
alaf server api /github/repos/acme/my-app/branches

# One repo, with its branches inlined
alaf server api /github/repos/acme/my-app --query branches=true

File browsing reads directly from GitHub:

• GET /api/github/repos/:owner/:repo/files — directory listing. Query: path (default repo root) and branch.
• GET /api/github/repos/:owner/:repo/file — one file's contents. Query: file (default package.json) and branch. .json files are parsed and returned as JSON.

curl "https://your-host/api/github/repos/acme/my-app/file?file=package.json&branch=main" \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN"

Webhooks

POST /api/github/repos/:owner/:repo/webhooks registers the Alaf Server push webhook on the repo (or reuses an existing one) so pushes trigger auto-deploy. It takes no request body — the target repo comes from the path. GET lists the repo's hooks. To remove one, DELETE with the hook id:

DELETE /api/github/repos/:owner/:repo/webhooks

alaf server api /github/repos/acme/my-app/webhooks -X DELETE -d '{"hookId":123456}'

Clone token

GET /api/github/repos/:owner/:repo/clone-token mints a short-lived (under an hour) GitHub App installation token and returns { token, cloneUrl, command } — a ready-to-run git clone. This is the same credential the build pipeline clones with, and is available only when the Alaf Server GitHub App is installed for the owner.

Errors you might see