リファレンスHTTP APIAgents

Turn one GitHub repository on or off for the agent

PUT
/v1/agents/{id}/github/repository-access

One toggle, one change, no release: a new session reads it at once, and turning a repository off reaches running sessions too. repository is a ref from GET …/github (selected_repositories, options.repositories) to turn a repository the catalog holds on or off, or installation_id with github_repository_id from GET …/github/repositories to turn on one the catalog may not hold yet; a repository is turned off by its ref only. The catalog row (added, or moved to a new name after a rename on GitHub), the settings, the receipts and the author App pin are written in one transaction, so a refusal or a failure anywhere leaves none of them. The change is applied to the row as it stands, so toggles of other repositories are kept and the last one of a repository stays. expected_revision is optional: left out, nothing is compared; given (null when there was no row) and different, the answer is 409 REVISION_CONFLICT with details.revision, and the caller reads GET …/github again. Turning off the repository start_repository_id names clears start_repository_id. An agent with no settings row starts from its active release's GitHub pins, read under the agent's lock; with no active release, or pins this image cannot read, that is 409 REVISION_CONFLICT with reason_code: settings_seed_unavailable. 400 reason_code: invalid_ref, repository_not_found, repository_not_allowed (the workspace's repository ceiling; a repository picked from an installation also needs a ceiling that runs on the App's repositories), app_required, name_held (another row has that name), no_author_app or not_installed (as POST …/github/repositories). Writes a set_agent_github receipt with result.change = "repository" when the settings changed; receipt_id is null when the repository already was in that state. Agent managers with a web session only; 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
repository*|
enabled*boolean
expected_revision?|null

Response Body

The repository is in the requested state.

application/json
  1. response
settings_revision*integer
Range-9007199254740991 <= value <= 9007199254740991
receipt_id*|null
enabled*boolean
repository*
Example Request
curl -X PUT 'https://example.com/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/github/repository-access' \  -H 'Content-Type: application/json' \  -d '{  "repository": {    "ref": "r1.d2Vyc3QtYXBw"  },  "enabled": true}'
Example Response
{  "settings_revision": 4,  "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c",  "enabled": true,  "repository": {    "ref": "r1.d2Vyc3QtYXBw",    "repository": "octo/werft-app",    "private": null  }}