Record who connected a GitHub App installation from the console
The console's setup page sends the state and installation_id GitHub's setup URL redirect carried. The state is spent first: unknown, spent, expired, issued to another caller or workspace, or for a connection that was removed or now holds another App answers 400 BAD_REQUEST state_invalid. The installation is read with the state's App's JWT (GET /app/installations/{id}): one that App does not have is 404 installation_not_found, and GitHub not answering is 502 GITHUB_UNAVAILABLE (github_unavailable or github_app_auth_failed). The caller and the time are recorded only when GitHub made the installation after the state, and only once: an installation that existed before, or already has someone recorded, answers recorded: false and keeps what it has. The setup URL's values can be forged, so the record is what GET …/github-settings shows as detail.connected and decides no access. Every answer carries Referrer-Policy: no-referrer. API keys are refused.
Auth: cookie session only; no scope. Idempotency-Key: ignored.
cookieSession__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.
id*stringThe workspace's id.
^([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)$uuidX-Requested-With?"werft-web"Required with a cookie session: the literal werft-web.
"werft-web"application/json- body
state*string^[A-Za-z0-9_-]{1,512}$installation_id*integer0 < value <= 9007199254740991The installation's connection, and whether it was recorded now.
application/json- response
connection_id*string^([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)$uuidinstallation_id*integer0 < value <= 9007199254740991recorded*booleancurl -X POST 'https://example.com/v1/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/github-apps/installations/complete' \ -H 'Content-Type: application/json' \ -d '{ "state": "state-from-the-redirect", "installation_id": 7654323}'{ "connection_id": "6f1b8c1e-3a4d-4f0a-9c7e-2b5d8e9f0a1b", "installation_id": 7654323, "recorded": true}