Workloads
Give pipelines, CI jobs, and services their own identity, with no personal sign-in and no stored secret.
Give each training job, scheduled pipeline, CI job, or deployed service its own identity in a Project, called a workload. A workload signs in with no person and no browser. When it runs on GitHub Actions, GCP, Kubernetes, AWS, or Modal, it uses the identity token that platform already issues, so there is no secret for you to store or rotate.
For example, the nightly-curation job in the demo Project reads new rows
from the frames Table and writes the ones worth keeping. You create a
nightly-curation workload, grant it editor in demo, and add a trust
policy that accepts GitHub Actions runs from your repository's main branch.
The job then signs in as nightly-curation on every run, with no key in your
CI secrets.
Why not use your own sign-in
A personal sign-in is a poor fit for automation. It starts in a browser, and it carries one person's roles, so the job can do everything that person can. When the person leaves the Organization, every job that uses their sign-in stops. A workload has its own ID, its own Project roles, and credentials that only the job can present, so you can give it exactly the access it needs and revoke it without affecting anyone else.
What a workload is
A workload is a machine identity that belongs to one
Project. Its ID starts with work_, such as
work_01GHI.
A new workload has no access. Its owning Project defines its identity and credentials. Grant it a role separately in each Project it needs to access, including its owning Project. The same workload ID can receive roles in other Projects, and Authorization decides what it can do in each one. See Grant Project access.
A Project editor can create a workload, but only a Project admin can add or
remove its keys and trust policies. A key or a trust policy lets its holder act
as the workload with all of the workload's grants, so controlling them is as
sensitive as granting the role itself.
How a workload signs in
A workload proves who it is in one of two ways:
| Method | How it works |
|---|---|
| Platform identity | The platform that runs the job, such as GitHub Actions, GCP, Kubernetes, AWS, or Modal, issues it a signed token. A trust policy on the workload names the issuer and the claims to accept. |
| Private key | The job signs a short-lived assertion with its private key. Spiral stores only the public key. |
Use a platform identity whenever the job runs on a supported platform: the platform issues a new token for each run, so no long-lived secret exists at all. Use a private key everywhere else, such as on an on-premises server.
Either way, Spiral never sees anything that could sign in as the job. The job
gets its platform token, or signs its assertion, in its own environment, and
Spiral returns an access token whose sub claim is the workload ID. The CLI
and the SDKs find a workload's credentials in the environment, so the same
code that runs as you on your laptop runs as the workload in production. See
How your code finds credentials.
Some older workloads sign in with a client secret (spw_...) instead. Spiral
still stores and accepts these secrets, but you should replace them with a
platform identity or a private key. See
Replace a client secret.
Where it runs
The Workloads API, which creates workloads and stores their trust policies
and public keys, is part of the Spiral API at https://api.spiraldb.dev. The
exchange of a platform token or key assertion for an access token happens at
https://auth.spiraldb.com. See Architecture.
HTTP API
New HTTP integrations use /api/workloads. List responses contain items and
an optional nextPageToken; follow it with the same credential, filters and
page size until absent. Trust policies use an array of claim key and value
objects. See the HTTP reference.
Guides
- Create a workload and grant it a Project role.
- Sign in with a platform identity from GitHub Actions, GCP, Kubernetes, AWS, Modal, or another OpenID Connect issuer.
- Sign in with a private key, and replace an older client secret.