Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 46 additions & 17 deletions .github/workflows/run-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,35 +50,61 @@ jobs:
spiral-integration:
runs-on: ubuntu-latest
# Only run on push/manual trigger — not on PRs — to avoid consuming SpiralDB
# resources on every review cycle.
# Requires the SPIRAL_WORKLOAD_ID secret and the SPIRAL_PROJECT_ID repository variable;
# fails loudly if either is absent so missing settings don't silently drop coverage. Runs only on the development repository:
# the public repository has no SpiralDB credentials, so the job is skipped there (ITL-1007).
# resources on every review cycle. Runs only on the development repository: the public
# repository has no SpiralDB credentials, so the job is skipped there (ITL-1007).
#
# Authentication (ITL-1185): a workload private key. pyspiral reads SPIRAL_CLIENT_ID (the
# workload id) and SPIRAL_PRIVATE_KEY (the workload's private key as a JWK naming its
# kid), signs a client assertion and requests a token from https://auth.spiraldb.com with
# the client_credentials grant. The job requests no GitHub OIDC token (no id-token
# permission): pyspiral's OIDC path posts a token exchange the server rejects. Requires
# the SPIRAL_CLIENT_ID and SPIRAL_PRIVATE_KEY secrets and the SPIRAL_PROJECT_ID repository
# variable; fails loudly, naming each missing setting, so missing settings don't silently
# drop coverage. Setup and key rotation: RELEASING.md, "SpiralDB integration job".
# The two secrets are given only to the two steps that read them, not to the job, so no
# third-party action sees them. The key is passed only through the environment, never on a
# command line. Never add a step that prints the environment (env, printenv, set -x) or
# the key to this job.
if: >-
github.repository == 'metamorphic-labs/orcapod-python'
&& (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
needs: test
# Runs beside the test jobs, not after them (developer, November 16, 2026; ITL-1185): it
# shares no artifact or output with them, and waiting hid for a long time that SpiralDB
# sign-in was failing.
permissions:
id-token: write # required to request a GitHub OIDC token for SpiralDB auth
contents: read
env:
SPIRAL_WORKLOAD_ID: ${{ secrets.SPIRAL_WORKLOAD_ID }}
SPIRAL_INTEGRATION_TESTS: "1"
SPIRAL_PROJECT_ID: ${{ vars.SPIRAL_PROJECT_ID }}
SPIRAL_SERVER_URL: https://api.spiraldb.dev # plain http no longer answers (ITL-1008); the repository variable of this name is not read

steps:
- name: Check for SPIRAL_WORKLOAD_ID
if: env.SPIRAL_WORKLOAD_ID == ''
- name: Check SpiralDB settings
# Prints only the names of missing settings and of missing JWK members, never a value.
env:
SPIRAL_CLIENT_ID: ${{ secrets.SPIRAL_CLIENT_ID }}
SPIRAL_PRIVATE_KEY: ${{ secrets.SPIRAL_PRIVATE_KEY }}
run: |
echo "::error::SPIRAL_WORKLOAD_ID secret is not set. SpiralDB integration tests cannot run. Configure the secret or investigate why it is missing."
exit 1

- name: Check for SPIRAL_PROJECT_ID
if: env.SPIRAL_PROJECT_ID == ''
run: |
echo "::error::SPIRAL_PROJECT_ID repository variable is not set. SpiralDB integration tests cannot run. Configure the variable or investigate why it is missing."
exit 1
missing=""
[ -n "$SPIRAL_CLIENT_ID" ] || missing="$missing SPIRAL_CLIENT_ID (secret)"
[ -n "$SPIRAL_PRIVATE_KEY" ] || missing="$missing SPIRAL_PRIVATE_KEY (secret)"
[ -n "$SPIRAL_PROJECT_ID" ] || missing="$missing SPIRAL_PROJECT_ID (repository variable)"
if [ -n "$missing" ]; then
echo "::error::SpiralDB integration tests cannot run; not set:$missing. See RELEASING.md, 'SpiralDB integration job'."
exit 1
fi
python3 - <<'PY'
import json, os, sys
try:
key = json.loads(os.environ["SPIRAL_PRIVATE_KEY"])
except ValueError:
key = None
if not isinstance(key, dict):
sys.exit("::error::SPIRAL_PRIVATE_KEY is not a JSON Web Key (a PEM key is not accepted). See RELEASING.md, 'SpiralDB integration job'.")
absent = [m for m in ("kty", "kid", "d") if not key.get(m)]
if absent:
sys.exit("::error::SPIRAL_PRIVATE_KEY lacks the JWK member(s) " + ", ".join(absent) + " (a private key JWK naming its registered kid is required). See RELEASING.md, 'SpiralDB integration job'.")
PY

- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
with:
Expand All @@ -99,6 +125,9 @@ jobs:
run: uv sync --locked --all-extras --dev --python "3.11"

- name: Run SpiralDB integration tests
env:
SPIRAL_CLIENT_ID: ${{ secrets.SPIRAL_CLIENT_ID }}
SPIRAL_PRIVATE_KEY: ${{ secrets.SPIRAL_PRIVATE_KEY }}
run: uv run --python "3.11" pytest tests/test_databases/test_spiraldb_connector_integration.py -v

license-check:
Expand Down
40 changes: 40 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,46 @@ environments:
5. Optional: set `CODECOV_TOKEN` there. The Codecov, SpiralDB and Linear jobs run only on
`metamorphic-labs` and are skipped on `nauticalab`.

### SpiralDB integration job

The `spiral-integration` job of `Run Tests` runs on every push to `main` and by hand
(`workflow_dispatch`) on `metamorphic-labs/orcapod-python`, never on pull requests. It runs
beside the test jobs, not after them, so its result comes in minutes. It authenticates to SpiralDB with a workload private key (ITL-1185): pyspiral reads
`SPIRAL_CLIENT_ID` (the workload id) and `SPIRAL_PRIVATE_KEY` (the private key as a JSON Web
Key) from the environment, signs a client assertion with the key, and requests a token from
`https://auth.spiraldb.com/oauth/token` with the `client_credentials` grant. It requests no
GitHub OIDC token: pyspiral's workload identity path posts a token exchange that the server
rejects. Client secrets are not used: the server no longer issues them. The job fails at its
first step, naming each missing setting, when one of the three below is not set or the key
is not a private JWK naming its `kid`. No agent creates, reads or sets any of them.

On `metamorphic-labs/orcapod-python` and in SpiralDB, the developer sets:

1. The SpiralDB workload the job runs as (today `orcapod-gha`) holds the **editor** role on
the test project ("Orcapod testing"): the tests create, write, read and drop tables there.
2. A key pair registered for that workload. pyspiral's own CLI has no command for this; use
Studio or the newer SpiralDB CLI, in an environment of its own and never installed beside
pyspiral (both provide a top-level `spiral` module):
`spiral workloads keys add <workload id> --kid <key id> --output -` prints the private key
as a JWK that names its `kid`. A PEM key is not accepted.
3. Repository secrets (`Settings → Secrets and variables → Actions → Secrets`):
`SPIRAL_CLIENT_ID`, the workload id (`work_...`), and `SPIRAL_PRIVATE_KEY`, the private JWK
as one line of JSON. Keep the key file out of the repository and delete it once the secret
is set.
4. Repository variable (`… → Variables`): `SPIRAL_PROJECT_ID`, the id of the test project.

The server URL is fixed in the workflow (`https://api.spiraldb.dev`); the repository variable
`SPIRAL_SERVER_URL` and the secret `SPIRAL_WORKLOAD_ID` are not read and can be deleted.

To rotate the key: add a new key to the workload with a new `kid`, replace the
`SPIRAL_PRIVATE_KEY` secret with the new JWK, run `Run Tests` by hand on `main` and check that
`spiral-integration` passes, then remove the old key (`spiral workloads keys rm`). A workload
can hold several keys, so the job keeps working during the switch.

If the key may have been exposed (for example printed in a log), remove it from the workload
first (`spiral workloads keys rm`), so it stops signing in at once, then add a new key and
replace the secret as above. The job fails in between; that is the price of containment.

## Pre-releases

Release candidates (e.g. `0.1.0rc1`) follow exactly the same path — enter the version in the
Expand Down
26 changes: 26 additions & 0 deletions docs/dev/design_issues/ITL-1185-CI1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
## `.github/workflows/run-tests.yml` — the SpiralDB integration job (ITL-1185)

### CI1 — `spiral-integration` failed on every push to `main`: SpiralDB rejected its sign-in
**Status:** resolved
**Severity:** high
**Issue:** ITL-1185

The `spiral-integration` job signed in to SpiralDB through a workload platform identity:
`SPIRAL_WORKLOAD_ID` plus a GitHub OIDC token (`id-token: write`). pyspiral 0.16.33 sends
that token to the API host as an OAuth token exchange, and the server stopped accepting
it (`422`: `grant_type` `token-exchange` unknown). Every test failed before any Orcapod code
ran, so every `Run Tests` run on `main` was marked failed even when the unit tests passed. The
repository variable `SPIRAL_PROJECT_ID` also named a project that no longer existed, and the
job ran only after the full test suite (`needs: test`), so each attempt to diagnose the
failure took about 40 minutes. SpiralDB has also retired workload client secrets, so a client
id and secret are not a replacement.

**Fix:** The job signs in with a workload private key, SpiralDB's current method: secrets
`SPIRAL_CLIENT_ID` (the workload id) and `SPIRAL_PRIVATE_KEY` (the private key as a JWK
naming its `kid`). pyspiral signs a JWT client assertion and requests a token from
`https://auth.spiraldb.com/oauth/token` with the `client_credentials` grant. The job requests no
OIDC token and no longer reads `SPIRAL_WORKLOAD_ID`. Its first step names each missing
setting, and refuses a key that is not a private JWK, printing names only. The two secrets are
given only to the two steps that read them, through the environment. The job runs beside the
test jobs, not after them. `RELEASING.md` ("SpiralDB integration job") covers the setup and key
rotation. A run by hand on the fix branch passed: 12 passed.
10 changes: 7 additions & 3 deletions tests/test_databases/test_spiraldb_connector_integration.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,13 @@

- Local dev: a saved ``spiral login`` (pyspiral keeps it in
``~/Library/Application Support/pyspiral/`` on macOS, ``~/.config/pyspiral/`` on Linux)
- CI (GitHub Actions): ``SPIRAL_WORKLOAD_ID`` env var pointing to a workload
that has editor access on the dev project and is bound to this repository via
GitHub OIDC (see internal CI/runbook docs for the exact workload/policy IDs).
- CI (GitHub Actions, the ``spiral-integration`` job of ``Run Tests``): a
workload private key in the ``SPIRAL_CLIENT_ID`` (workload id) and
``SPIRAL_PRIVATE_KEY`` (private JWK naming its ``kid``) env vars, which pyspiral
reads to request a token from ``https://auth.spiraldb.com``. The workload holds
the editor role on the test project. The developer sets both repository
secrets; setup and key rotation are in ``RELEASING.md`` ("SpiralDB integration
job").

If the env var is set but credentials are absent, the tests fail rather than
skip — the operator is expected to ensure auth is in place when enabling
Expand Down
Loading