Machine credentials
How a project's owner gives automation, such as a repository's workflow, a credential to call Sparrow with.
Automation, such as a GitHub repository's workflow, can't sign in as a person. A project's owner gives it a machine credential instead (ADR-0018). It reaches two things, and only for this project's tasks:
- Read a task's workflow and status (
GET /v1/tasks/{taskId}/workflow), for example to check that a ticket named in a commit allows its pull request to land without a person. - Record whether a task's automated checks passed (
POST /v1/tasks/{taskId}/check-resultswith{"passed": true}orfalse). Passed moves any of the project's tasks that isn't Completed or Cancelled to Completed, whether or not itsreviewRequiresValidationis on; failed moves it to Blocked. The task's history names the credential (ADR-0026).
To create one, open the project, then Credentials (owners only), then New credential.
Name what will use it. Your browser makes the key pair and sends Sparrow only the public key.
The credentials JSON, with the private key, is shown once: copy or download it and store it as
a secret where the client reads it, such as the GitHub Actions secret SPARROW_CREDENTIALS.
A project holds at most two credentials, so a client can move to a new one while the old one
still works; deleting a credential refuses its tokens from the next request.
A client signs a short-lived ES256 token with the private key for each call. Sparrow's own client does that:
pip install "pyjwt[crypto]"
export SPARROW_CREDENTIALS='<the credentials JSON>'
PYTHONPATH=service-sparrow/src python -m sparrow.ci workflow SPR-19
PYTHONPATH=service-sparrow/src python -m sparrow.ci check-results SPR-19 --passed