リファレンスHTTP APIWorkspace settings

A page of the GitHub Apps' repositories, and the catalog's (owner or admin)

GET
/v1/workspaces/{id}/github-repositories

The repositories one installation of the workspace's GitHub Apps reaches, a page at a time as GitHub pages them (GET /installation/repositories): installation_id picks the installation (absent: the first not suspended, the author App's before the reviewer App's, by account; while the role read first has several connections, absent is 400 installation_required), page and per_page (at most 100) the page, and total_count is GitHub's count. installations lists the author App's installations, then the reviewer App's, each with its App's connection_id and role, the permissions the account approved, and repository_count (GitHub's count, asked for the first 20 installations; null past them or when GitHub did not give it). An App GitHub does not answer for leaves its installations out. Nothing is registered: a repository becomes a catalog row when an agent's manager picks it (POST /v1/agents/{id}/github/repositories), and catalog_id then names it; agent_count counts agents whose active release names it, and on a reviewer App's page only those that turn review on. unavailable says why the page is empty: no_author_app, no_installation, or, with no installation_id named, GitHub not answering (github_unavailable or github_app_auth_failed, the author App's cause first) or every installation suspended (installation_suspended); then catalog and the installations that were read still come back, to name one. catalog lists the rows picks resolved or a seed left (source selection, console or seed; their branch is changed with PATCH), each with its agent_count; installed says whether an installation of any author App covers a row now (asked for the first 100 rows; null past them, or when GitHub could not answer for an App and none said yes), and a row's pins names the connection each role's work uses (GET …/app-pins for the choices). An installation id no registered App has, or one GitHub no longer has, is 404 installation_not_found; a suspended one is 409 INSTALLATION_SUSPENDED; GitHub not answering for the App that may hold a named installation is 502 GITHUB_UNAVAILABLE (github_unavailable is worth retrying, github_app_auth_failed is not). API keys are refused.

Auth: cookie session only; no scope.

Authorization

cookieSession
cookie__Host-werft_session<token>

For the web console: the browser session cookie set by POST /v1/auth/login. It holds the scopes of the user's workspace role (owner: all; admin and member: all but sessions:recover). Requests other than GET must also send X-Requested-With: werft-web.

Path Parameters

id*string

The workspace's id.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Query Parameters

installation_id?integer

The GitHub App installation to list. Required while the role has several connections.

Range0 < value <= 9007199254740991
page?integer

The page of GitHub's listing, from 1.

Range1 <= value <= 1000
Default1
per_page?integer

How many repositories GitHub puts on a page.

Range1 <= value <= 100
Default30

Response Body

The page and the catalog's repositories.

application/json
  1. response
installations*array<>
installation_id*|null
page*integer
Range1 <= value <= 9007199254740991
per_page*integer
Range1 <= value <= 9007199254740991
total_count*integer
Range0 <= value <= 9007199254740991
repositories*array<>
unavailable*|null
catalog*array<>
Example Request
curl -X GET 'https://example.com/v1/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/github-repositories'
Example Response
{  "installations": [    {      "id": 4242,      "account": "acme",      "connection_id": "019a0000-0000-7000-8000-0000000000b1",      "role": "author",      "permissions": {        "contents": "write",        "pull_requests": "write",        "metadata": "read"      },      "repository_count": 1    }  ],  "installation_id": 4242,  "page": 1,  "per_page": 30,  "total_count": 1,  "repositories": [    {      "github_repository_id": 123456789,      "full_name": "acme/app",      "default_branch": "main",      "private": true,      "catalog_id": "app",      "agent_count": 2    }  ],  "unavailable": null,  "catalog": [    {      "id": "app",      "github_repository_id": 123456789,      "full_name": "acme/app",      "url": "https://github.com/acme/app.git",      "branch": "main",      "source": "selection",      "version": 1,      "installed": true,      "updated_at": "2026-11-01T09:00:00Z",      "agent_count": 2    }  ]}