From 156c3e500399b2781a87864c00225a8ed9683a2b Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Mon, 16 Nov 2026 19:42:49 -0800 Subject: [PATCH 1/5] ci(spiral): authenticate the SpiralDB integration job with workload client credentials (ITL-1185) The SpiralDB server rejects the OIDC token exchange (422, grant_type token-exchange unknown), so every spiral-integration run on main failed before any test ran. The job now passes SPIRAL_CLIENT_ID and SPIRAL_CLIENT_SECRET (repository secrets), which pyspiral reads to request a token with the client_credentials grant, and no longer requests a GitHub OIDC token (id-token permission and SPIRAL_WORKLOAD_ID removed). - One check step fails loudly, naming each missing setting among SPIRAL_CLIENT_ID, SPIRAL_CLIENT_SECRET and SPIRAL_PROJECT_ID, and never prints a value. - The two secrets are given only to the check step and the test step, not to the job, so no third-party action sees them. - RELEASING.md gains a "SpiralDB integration job" setup section: the two secrets, the variable, the workload's editor grant, and rotation. - The integration test module docstring describes the new CI auth. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/run-tests.yml | 46 ++++++++++++------- RELEASING.md | 28 +++++++++++ .../test_spiraldb_connector_integration.py | 9 ++-- 3 files changed, 64 insertions(+), 19 deletions(-) diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 745133b7b..306fd1de0 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -50,35 +50,46 @@ 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): workload client credentials. pyspiral reads SPIRAL_CLIENT_ID + # and SPIRAL_CLIENT_SECRET from the environment and requests a token with the + # client_credentials grant. The SpiralDB server no longer accepts the OIDC token exchange, + # so the job requests no GitHub OIDC token (no id-token permission). Requires the + # SPIRAL_CLIENT_ID and SPIRAL_CLIENT_SECRET secrets and the SPIRAL_PROJECT_ID repository + # variable; fails loudly, naming each missing setting, so missing settings don't silently + # drop coverage. Setup and secret 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. Never add a step that prints the environment (env, + # printenv, set -x) to this job. if: >- github.repository == 'metamorphic-labs/orcapod-python' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') needs: test 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 + # Tests only whether each setting is empty and prints only the names of the + # missing ones, never a value. + env: + SPIRAL_CLIENT_ID: ${{ secrets.SPIRAL_CLIENT_ID }} + SPIRAL_CLIENT_SECRET: ${{ secrets.SPIRAL_CLIENT_SECRET }} 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_CLIENT_SECRET" ] || missing="$missing SPIRAL_CLIENT_SECRET (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 - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: @@ -99,6 +110,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_CLIENT_SECRET: ${{ secrets.SPIRAL_CLIENT_SECRET }} run: uv run --python "3.11" pytest tests/test_databases/test_spiraldb_connector_integration.py -v license-check: diff --git a/RELEASING.md b/RELEASING.md index 9f9132a74..22734bbf6 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -191,6 +191,34 @@ 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 +authenticates to SpiralDB with workload client credentials (ITL-1185): pyspiral reads +`SPIRAL_CLIENT_ID` and `SPIRAL_CLIENT_SECRET` from the environment and requests a token with +the `client_credentials` grant. It requests no GitHub OIDC token: the SpiralDB server no +longer accepts the OIDC token exchange. The job fails at its first step, naming each missing +setting, when one of the three below is not set. 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. Repository secrets (`Settings → Secrets and variables → Actions → Secrets`): + `SPIRAL_CLIENT_ID` and `SPIRAL_CLIENT_SECRET`, both from + `spiral workloads issue-creds `. The secret is shown once, when it is issued. +3. 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 secret: issue new credentials for the workload +(`spiral workloads issue-creds `), replace both repository secrets with the new +pair, run `Run Tests` by hand on `main` and check that `spiral-integration` passes, then revoke +the old pair (`spiral workloads revoke-creds `). Rotate at once if a secret may +have been exposed, for example printed in a log. + ## Pre-releases Release candidates (e.g. `0.1.0rc1`) follow exactly the same path — enter the version in the diff --git a/tests/test_databases/test_spiraldb_connector_integration.py b/tests/test_databases/test_spiraldb_connector_integration.py index ccb6d5293..7a98821ee 100644 --- a/tests/test_databases/test_spiraldb_connector_integration.py +++ b/tests/test_databases/test_spiraldb_connector_integration.py @@ -6,9 +6,12 @@ - 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``): workload + client credentials in the ``SPIRAL_CLIENT_ID`` and ``SPIRAL_CLIENT_SECRET`` env + vars, which pyspiral reads to request a token with the ``client_credentials`` + grant. The workload holds the editor role on the test project. The developer + sets both repository secrets; setup and 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 From 505ef57ef121779f32ace6aa7313f4d3693118fc Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Mon, 16 Nov 2026 19:47:17 -0800 Subject: [PATCH 2/5] ci(spiral): authenticate the SpiralDB integration job with a workload private key (ITL-1185) The server no longer issues workload client secrets, so the job uses a workload key pair instead: SPIRAL_CLIENT_ID (workload id) and SPIRAL_PRIVATE_KEY (private JWK naming its kid). pyspiral 0.16.33 signs a client assertion with the key and requests a token from https://auth.spiraldb.com/oauth/token (client_credentials grant). - The check step names each missing setting and refuses a key that is not a private JWK with kty, kid and d, printing only member names. - The key reaches pyspiral only through step environment, never argv. - RELEASING.md describes registering the key, the secrets and rotation. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/run-tests.yml | 41 ++++++++++++------- RELEASING.md | 37 ++++++++++------- .../test_spiraldb_connector_integration.py | 13 +++--- 3 files changed, 57 insertions(+), 34 deletions(-) diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 306fd1de0..11983a7d5 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -53,16 +53,18 @@ jobs: # 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): workload client credentials. pyspiral reads SPIRAL_CLIENT_ID - # and SPIRAL_CLIENT_SECRET from the environment and requests a token with the - # client_credentials grant. The SpiralDB server no longer accepts the OIDC token exchange, - # so the job requests no GitHub OIDC token (no id-token permission). Requires the - # SPIRAL_CLIENT_ID and SPIRAL_CLIENT_SECRET secrets and the SPIRAL_PROJECT_ID repository + # 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 secret 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. Never add a step that prints the environment (env, - # printenv, set -x) to this job. + # 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') @@ -76,20 +78,31 @@ jobs: steps: - name: Check SpiralDB settings - # Tests only whether each setting is empty and prints only the names of the - # missing ones, never a value. + # Prints only the names of missing settings and of missing JWK members, never a value. env: SPIRAL_CLIENT_ID: ${{ secrets.SPIRAL_CLIENT_ID }} - SPIRAL_CLIENT_SECRET: ${{ secrets.SPIRAL_CLIENT_SECRET }} + SPIRAL_PRIVATE_KEY: ${{ secrets.SPIRAL_PRIVATE_KEY }} run: | missing="" [ -n "$SPIRAL_CLIENT_ID" ] || missing="$missing SPIRAL_CLIENT_ID (secret)" - [ -n "$SPIRAL_CLIENT_SECRET" ] || missing="$missing SPIRAL_CLIENT_SECRET (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: @@ -112,7 +125,7 @@ jobs: - name: Run SpiralDB integration tests env: SPIRAL_CLIENT_ID: ${{ secrets.SPIRAL_CLIENT_ID }} - SPIRAL_CLIENT_SECRET: ${{ secrets.SPIRAL_CLIENT_SECRET }} + 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: diff --git a/RELEASING.md b/RELEASING.md index 22734bbf6..3364f057b 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -195,29 +195,38 @@ environments: 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 -authenticates to SpiralDB with workload client credentials (ITL-1185): pyspiral reads -`SPIRAL_CLIENT_ID` and `SPIRAL_CLIENT_SECRET` from the environment and requests a token with -the `client_credentials` grant. It requests no GitHub OIDC token: the SpiralDB server no -longer accepts the OIDC token exchange. The job fails at its first step, naming each missing -setting, when one of the three below is not set. No agent creates, reads or sets any of them. +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. Repository secrets (`Settings → Secrets and variables → Actions → Secrets`): - `SPIRAL_CLIENT_ID` and `SPIRAL_CLIENT_SECRET`, both from - `spiral workloads issue-creds `. The secret is shown once, when it is issued. -3. Repository variable (`… → Variables`): `SPIRAL_PROJECT_ID`, the id of the test project. +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 --kid --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 secret: issue new credentials for the workload -(`spiral workloads issue-creds `), replace both repository secrets with the new -pair, run `Run Tests` by hand on `main` and check that `spiral-integration` passes, then revoke -the old pair (`spiral workloads revoke-creds `). Rotate at once if a secret may -have been exposed, for example printed in a log. +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. Rotate at once if the key +may have been exposed, for example printed in a log. ## Pre-releases diff --git a/tests/test_databases/test_spiraldb_connector_integration.py b/tests/test_databases/test_spiraldb_connector_integration.py index 7a98821ee..de32f9f20 100644 --- a/tests/test_databases/test_spiraldb_connector_integration.py +++ b/tests/test_databases/test_spiraldb_connector_integration.py @@ -6,12 +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, the ``spiral-integration`` job of ``Run Tests``): workload - client credentials in the ``SPIRAL_CLIENT_ID`` and ``SPIRAL_CLIENT_SECRET`` env - vars, which pyspiral reads to request a token with the ``client_credentials`` - grant. The workload holds the editor role on the test project. The developer - sets both repository secrets; setup and rotation are in ``RELEASING.md`` - ("SpiralDB integration job"). +- 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 From 7591150d929a7fbe4884543a8eddd1605cae1906 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Mon, 16 Nov 2026 20:08:04 -0800 Subject: [PATCH 3/5] ci(spiral): run spiral-integration beside the test jobs, not after them (ITL-1185) Co-Authored-By: Claude Fable 5.2 --- .github/workflows/run-tests.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 11983a7d5..f5083fe73 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -68,7 +68,9 @@ jobs: 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: contents: read env: From d3ce71568b1cb33135f34e95366c3449fca11d57 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Mon, 16 Nov 2026 20:13:57 -0800 Subject: [PATCH 4/5] docs(spiral): log ITL-1185 as resolved design issue CI1; note the job runs beside the tests - docs/dev/design_issues/ITL-1185-CI1.md: the SpiralDB sign-in failure, its causes and the fix (workload private key, no OIDC, own job order). - RELEASING.md: the SpiralDB section says the job runs beside the test jobs (7591150d). Co-Authored-By: Claude Opus 5.5 --- RELEASING.md | 4 ++-- docs/dev/design_issues/ITL-1185-CI1.md | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 2 deletions(-) create mode 100644 docs/dev/design_issues/ITL-1185-CI1.md diff --git a/RELEASING.md b/RELEASING.md index 3364f057b..01ee68e92 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -194,8 +194,8 @@ environments: ### 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 -authenticates to SpiralDB with a workload private key (ITL-1185): pyspiral reads +(`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 diff --git a/docs/dev/design_issues/ITL-1185-CI1.md b/docs/dev/design_issues/ITL-1185-CI1.md new file mode 100644 index 000000000..a1938a940 --- /dev/null +++ b/docs/dev/design_issues/ITL-1185-CI1.md @@ -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. From 7613f9e8ebf27d38e2f434e474c15ad47155b795 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Mon, 16 Nov 2026 20:14:44 -0800 Subject: [PATCH 5/5] docs(spiral): remove a possibly exposed key first, then rotate (ITL-1185) Routine rotation adds the new key, verifies, then removes the old one; for a key that may have been exposed that order keeps it usable until a run passes. RELEASING.md now says to remove such a key at once, then add a new one (CodeRabbit security note on the earlier head). Co-Authored-By: Claude Opus 5.5 --- RELEASING.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 01ee68e92..9b97adfe8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -225,8 +225,11 @@ The server URL is fixed in the workflow (`https://api.spiraldb.dev`); the reposi 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. Rotate at once if the key -may have been exposed, for example printed in a log. +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