Skip to content
Manybases
esc

Search pages and sections. Try a tool name, an error code, a route.

↑↓ navigate↵ openesc close
  1. API reference
  2. Management plane
  3. GitHub integration
Docs

API reference · Management plane

GitHub integration

Connect a GitHub account or organization to a Manybases account, link a repository to a project, and let a GitHub Actions run deploy the project's site without any secret stored anywhere.

Host: https://api.manybases.com · Key: ak_. The account routes require a signed-in human; the link routes serve on the key alone except the unlink.

The property#

A GitHub repository can deploy a site only onto a project of the account, and only if it belongs to a GitHub App installation that a human of the account approved — and no key value ever exists in that repository. The workflow proves which repository it runs in (a token GitHub signs for the run), and every upload is checked against the link.

The App only reads which repositories exist: it never reads code, writes a file, sets a secret or touches a workflow. The anchor of a link is the repository's numeric id, never its name: a renamed repository keeps its id, and the name it frees can be registered by anyone.

Account routes — the connection#

All four require X-Account-Session, the list included: it carries the logins of the connected organizations, which an agent has no reason to see. Connecting is a human gesture, done from the dashboard's Integrations screen; no tool exposes it. An account key limited to some projects receives 403 on all four.

GET/v1/account/github/installations
The App (slug, client_id, install_url, authorize_url, callback_path) and the account's installations, removed ones included: installation_id (a string), account: { login, id, type } (User or Organization), connected_at, revoked_at
POST/v1/account/github/installations { code, code_verifier, installation_id? }
Finishes an authorization started on GitHub. 201, or 200 if already connected. With no preselection and several installations visible, 200 { candidates } and nothing is written — pick one and authorize again
GET/v1/account/github/installations/:iid/repositories
The repositories the installation covers: repository_id (a string), full_name, private, archived, default_branch, plus repository_selection, total_count, truncated
DELETE/v1/account/github/installations/:iid
Disconnects: removes the installation from the account and every repository link it carries; { installation_id, links_dropped }. Sites already deployed keep serving. Does not uninstall the App on GitHub

Refusals of the POST, in order: 400 (body, or a code GitHub refused — a code is single-use, and a failed attempt burns it), 404 readable (GitHub shows this person no installation), the neutral 404 (the preselected installation is not visible to this person), 403 (not an active admin of the organization), 409 (installation suspended on GitHub, already connected to another account, or recorded as removed), 502/503. The user token GitHub issues exists only for the duration of the POST: the product revokes it before answering and never stores it.

Project routes — the link#

GET/v1/projects/:pid/github/repository
Toolget_github_link
Whoak_
Effect{ link } or link: null — a valid answer, distinct from "this project does not exist". The link carries repository_id and installation_id (strings), repository_full_name, project_id
PUT/v1/projects/:pid/github/repository { repository_id, installation_id? }
Toollink_repo
Whoak_
Effect201 if there was no link, 200 if there was — the response carries replaced, the link that just lost the right to deploy, or null. The repository name comes from GitHub, never from the body
DELETE/v1/projects/:pid/github/repository
Tool—
Whoak_ + signed-in human
Effect{ project_id, link, already_gone }. Replaying answers 200 with already_gone: true. The deployed site keeps serving
  • If installation_id is omitted, the server probes at most three live installations of the account and keeps the first that covers the repository. More than three, or an unreadable installation, answer 502 — never "not covered".
  • "Not covered" — the repository does not belong to an installation the account approved — answers 404, byte-identical to an unknown repository; only the hint names the fix: a human opens the GitHub URL, adds the repository to the installation (or switches it to all repositories), and the call is made again. Nothing in the body can repair that refusal.
  • A project has one repository; a repository can serve several projects.
  • Coverage is checked at link time, never after. An installation that later stops covering a repository leaves the link in place.
  • An X-Account-Session on the PUT names the link's author without being required; a present but invalid one answers 401.

What stops a repository from deploying#

Two gestures, of different natures:

  • Disconnecting at Manybases (Integrations → GitHub, or the DELETE above) erases the installation and its links at once. Unlinking a project from its Deploy tab cuts that one link at once — the link is checked on every upload, not once.
  • Removing the App on GitHub changes nothing on the instant. Every five minutes the product asks GitHub about five installations of its registry, in a rolling window: with at most five live installations, each is re-checked within ten minutes. An installation GitHub no longer knows is marked removed — its line stays, for the history, and its links stop authorizing: pushes from those repositories receive the neutral 404. Until then, a push still replaces the site. A suspended installation is not removed. To stop at once, disconnect from the dashboard.

What this does not guarantee#

Anyone who can push to the linked repository can deploy the project's site. This is GitHub's authorization model, not ours: the link is on the repository, not on a branch. If the installation covers all repositories, an agent can link any of them — an old repository with outside collaborators, linked by an agent, gives those people a deployment right on the project. The dashboard recommends All repositories, so that your agent can deploy the repositories it creates; if some repositories of that account should never deploy, pick a selection instead — each repository your agent creates then has to be added to the installation before it can deploy.