diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 745133b7b..f5083fe73 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -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: @@ -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: diff --git a/RELEASING.md b/RELEASING.md index 9f9132a74..9b97adfe8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -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 --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 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 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. diff --git a/tests/test_databases/test_spiraldb_connector_integration.py b/tests/test_databases/test_spiraldb_connector_integration.py index ccb6d5293..de32f9f20 100644 --- a/tests/test_databases/test_spiraldb_connector_integration.py +++ b/tests/test_databases/test_spiraldb_connector_integration.py @@ -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