ReferenceHTTP APIAgents

Resolve an App repository to the catalog id the settings name

POST
/v1/agents/{id}/github/repositories

Takes a repository from GET …/github/repositories and returns the catalog id to put in settings.repositories of the next PUT /v1/agents/{id}/github/settings; nothing about the agent's settings or releases changes. The server reads the repository by its GitHub id and checks that the named installation covers it, then takes its URL and default branch from GitHub. The same repository always resolves to the same id, by its GitHub id: the first pick writes a resolve_repository receipt (receipt_id), and so does a pick after a rename on GitHub, which moves the row to the new name and URL; other picks return null. A repository with no author pin yet is pinned to the connection whose App holds the installation (a set_repository_github_app receipt), and connection_id names the author connection it is pinned to; a pin made before stays. 400 details.reason_code: repository_not_allowed (the workspace's ceiling does not run on App repositories), no_author_app, not_installed (the author App has no such installation, or it does not cover the repository), or name_held (another row has that name: another GitHub repository's, whose pick after its rename frees the name, or one not yet tied to a GitHub id). GitHub not answering is 502 GITHUB_UNAVAILABLE, and an installation GitHub dropped while it was read is 404 installation_not_found; nothing stored changed. A signed-in manager of the agent; API keys are refused.

Auth: cookie session only; no scope. Idempotency-Key: ignored.

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 agent'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

Header Parameters

X-Requested-With?"werft-web"

Required with a cookie session: the literal werft-web.

Value in"werft-web"

Request Body

application/json
  1. body
installation_id*integer
Range0 < value <= 9007199254740991
github_repository_id*integer
Range0 < value <= 9007199254740991

Response Body

The catalog id, and the receipt when this pick added or renamed its row.

application/json
  1. response
catalog_id*string
Length1 <= length
receipt_id*|null
connection_id?string
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
Example Request
curl -X POST 'https://example.com/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/github/repositories' \  -H 'Content-Type: application/json' \  -d '{  "installation_id": 4242,  "github_repository_id": 123456789}'
Example Response
{  "catalog_id": "app",  "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c"}