API reference

GitHub and repositories

An organization connects GitHub App installations so its members can run on their repositories and discover Workbench packages in them. How runs use GitHub is on Repositories and pull requests.

Connecting an installation is an interactive browser flow done from the dashboard's sources page. Its routes are session only:

Method	Path	Auth	Purpose
POST	`/v1/authorizations`	Session: manager	Start a GitHub authorization. Body `{ "organization_id", "installation_id"?, "return_to"?: "sources" or "onboarding" }`. Returns `{ "authorization_url", "install_url" }`.
PATCH	`/v1/authorizations/:id`	Session: the authorization's owner	Continue with a newly installed `installation_id`. Same response.
POST	`/v1/installations/candidates`	Session: the authorization's owner	List what GitHub's OAuth `code` reaches. Links nothing.
POST	`/v1/installations`	Session: the authorization's owner	Link exactly the chosen installations. Body `{ "state", "selection", "installation_ids" }`.
GET	`/v1/installations?organization_id=<uuid>`	Session: member	Connected installations and, for managers, reusable ones.
POST	`/v1/installations/discoveries`	Session: manager	List the installations the user can reach from their saved GitHub authorization, without a new GitHub prompt. Body `{ "organization_id", "return_to" }`. Returns `{ "status": "connected", "state", "listing" }`, or `{ "status": "disconnected" }` or `{ "status": "expired" }`.
DELETE	`/v1/installations/:id`	Session: manager	Unlink an installation. Returns `{ "deleted": true }`.

Each candidate has a status: linkable (no organization links it), linked (this one already does), reusable (another organization you belong to links it), or unavailable, with a reason. Being able to see an installation is not enough to link it: on a personal account it must be yours, and on a GitHub organization you must be an active admin. A selection token is valid for 10 minutes, and linking ends the authorization.

The installation object has id, organization_id, installation_id, account_id, account_login, account_type (Organization or User), settings_url, created_at, and updated_at.

Repositories#

Repositories synced from the organization's installations.

The repository object#

Field	Meaning
`id`, `organization_id`, `github_installation_id`	UUIDs.
`github_id`	GitHub's repository ID.
`owner`, `name`, `url`
`default_branch`
`visibility`	`public` or `private`.
`status`	`active`, `unavailable`, or `removed`.
`last_commit`, `last_synced_at`	Or null.
`created_at`, `updated_at`

List repositories#

GET /v1/repositories?organization_id=<uuid>

Key catalog:read, or session: member. Response 200 { "repositories": [ ... ] }.

Refresh repositories#

POST /v1/syncs with { "organization_id": "uuid" }

Key packages:write, or session: member. Reads repositories from every installation again. Response 201 { "repositories": [ ... ] }.

Discover packages#

POST /v1/discoveries with { "repository_id": "uuid" }

Key packages:write, or session: member. Finds .workbenches/* packages in a repository at its current commit, through GitHub's API. Nothing is cloned.

Response 201:

{
    "repository_id": "uuid",
    "source_commit": "4f2c...",
    "workbenches": [
        {
            "source_path": ".workbenches/core/workbench.yml",
            "slug": "core",
            "valid": true,
            "errors": [],
            "manifest": {
                "spec": 1,
                "version": "0.1.0",
                "name": "core",
                "...": "..."
            }
        }
    ]
}

Submit discovered packages for review with the GitHub form of POST /v1/submissions; see Workbenches and registry.