You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
ci(spiral): authenticate the SpiralDB integration job with a workload private key (ITL-1185) - #414
The spiral-integration job of Run Tests failed on every push to main. It signed in through a workload platform identity (SPIRAL_WORKLOAD_ID plus a GitHub OIDC token), which pyspiral sends to the API host as a token exchange. The SpiralDB server now rejects that exchange (422: grant_typetoken-exchange unknown), so every test failed before any Orcapod code ran. SpiralDB has also retired workload client secrets.
Workload private key. 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 with the key and requests a token from https://auth.spiraldb.com/oauth/token with the client_credentials grant.
No OIDC. The id-token: write permission is removed (contents: read stays), and the job no longer reads SPIRAL_WORKLOAD_ID. SPIRAL_PROJECT_ID (repository variable) and the hardcoded https://api.spiraldb.dev server URL are unchanged.
Loud check. The first step names each missing setting among SPIRAL_CLIENT_ID, SPIRAL_PRIVATE_KEY and SPIRAL_PROJECT_ID. It also refuses a key that is not a private JWK with kty, kid and d (a PEM key, for example). It prints only names, never a value.
Secret hygiene. The two secrets go only to the check step and the test step, through the environment and never on a command line, so the third-party actions (checkout, setup-uv, setup-python) never see them. No step prints the environment.
Runs beside the test jobs (needs: test removed; developer decision, 7591150d). The job shares no artifact or output with the test jobs, and it runs only on pushes to main and by hand. Its result now comes in minutes instead of after the full suite, and a failing test job no longer hides whether SpiralDB sign-in works. Nothing depends on the order: no job needs spiral-integration, and there is no concurrency group or job output.
Docs.RELEASING.md gains a "SpiralDB integration job" section under one-time setup: the editor grant, registering the key, both secrets, the variable, and key rotation. The test module docstring describes the CI sign-in. docs/dev/design_issues/ITL-1185-CI1.md records the issue as resolved.
No change under src/, no golden file, no changelog fragment (CI only; changelog.d/README.md).
The branch history keeps a first commit (156c3e50) that used a client id and secret; 505ef57e replaced it with the key pair before anything ran, and no trace of the secret variant remains in the final diff.
======================= 12 passed, 5 warnings in 48.89s ========================
The job log shows both secrets only as ***, and no key material appears in it.
pyspiral 0.16.33 (the locked version) was checked with a throwaway JWK generated locally and a workload id that doesn't exist. It sends exactly the documented request: client_credentials with a jwt-bearer client assertion (ES256, kid in the header, iss = sub = workload id, aud = the token endpoint, 60 s expiry). The key pair takes precedence over SPIRAL_CLIENT_SECRET and SPIRAL_WORKLOAD_ID.
The check step's script was run under bash -e. It passes with a valid key. With a missing setting, a PEM key, a JWK without kid, or a public-only JWK, it fails with names only.
actionlint, ruff, basedpyright and scripts/design_issues.py --check are clean.
Left for the developer (no agent touches settings)
Delete the unused SPIRAL_WORKLOAD_ID secret.
Delete (or stop maintaining) the stale SPIRAL_SERVER_URL repository variable. The workflow hardcodes the https URL and does not read it.
…lient 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 <noreply@anthropic.com>
The spiral-integration job of the Run Tests workflow runs only on pushes to main (and by hand) on the development repository. It has failed on every recent push, which marks every Run Tests run on main as failed even when the three test jobs pass (observed on November 16, 2026, on eight consecutive commits; none of the last 100 runs on main concluded green).
Diagnosis (coordinator, November 16, 2026; read-only checks):
Authentication: the job authenticates with a GitHub OIDC token through a SpiralDB workload (SPIRAL_WORKLOAD_ID). The server answers 422 Unprocessable Entity on its token endpoint: grant_type: unknown variant urn:ietf:params:oauth:grant-type:token-exchange, expected client_credentials or refresh_token. Every test fails there, before any Orcapod code runs. The one test that passes never contacts the server.
The repository variable SPIRAL_PROJECT_ID names a project that no longer exists on the server (404). The current test project is the one named "Orcapod testing", which has a workload named orcapod-gha.
That workload's only OIDC trust policy is for the repository nauticalab/orcapod-python, while the job runs only on metamorphic-labs/orcapod-python.
That workload has no access grant on the project (the grants are for organization roles and one user).
The repository variable SPIRAL_SERVER_URL still holds the plain http address; the workflow hardcodes the https address and does not read it (ITL-1008).
The same test file passes with a working login: 12 passed on the v0.3.0 release commit against the current test project.
Goals & Success Criteria
The job authenticates with a grant the server accepts: workload client credentials (SPIRAL_CLIENT_ID and SPIRAL_CLIENT_SECRET, which pyspiral reads from the environment), stored as repository secrets. The workflow no longer requests an OIDC token for this job.
The workload has the editor role on the test project, and SPIRAL_PROJECT_ID names that project.
The job is green on main, so a Run Tests run on main is green when the tests pass. A run by hand (workflow_dispatch) on the fix branch proves it before merge.
The job still fails loudly, with a message that says what to set, when a secret or the variable is missing.
The stale SPIRAL_SERVER_URL variable is removed or corrected, and the unused SPIRAL_WORKLOAD_ID secret is removed (developer).
RELEASING.md or the workflow comment states how the job authenticates and how to rotate the credentials.
Scope & Boundaries
In scope:
.github/workflows/run-tests.yml (the spiral-integration job) and the documentation of its setup.
Out of scope:
Creating credentials, secrets, variables, grants or workload policies: the developer does these; no agent does.
Orcapod's SpiralDB connector, which is not at fault.
Dependencies & Risks
A client secret is a long-lived credential, unlike an OIDC exchange: it needs rotation and must never be printed in logs.
Whether the server will accept the OIDC token exchange again (a pyspiral or server version question) is open; if it does, OIDC with a policy for the development repository is the better long-term setup.
No actionable comments were generated in the recent review.
Walkthrough
The SpiralDB integration job replaces GitHub OIDC authentication with private-JWK client credentials. It checks the required secrets and project ID, validates key fields, and passes credentials to the integration test. The job runs alongside the test jobs. Documentation describes setup and key rotation.
Changes: SpiralDB integration authentication
Layer / File(s)
Summary
Workflow credentials and validation .github/workflows/run-tests.yml
The workflow replaces OIDC authentication with SPIRAL_CLIENT_ID and SPIRAL_PRIVATE_KEY. It reports missing credentials or project ID, and rejects a key that is not a JSON object or lacks kty, kid, or d. The integration-test step receives both secrets. The job runs alongside the test jobs.
The release guide and test documentation describe the workload-key setup, project access, and key rotation. The issue document records the reported failure, the described fix, and a test result.
This change moves the SpiralDB integration job to private-key authentication and updates the setup docs. The author reports a successful manual run, and no merge-blocking issues were found.
Security architecture risk: Low · up to 7613f
The reusable private key extends the consequences of a compromised integration-test run beyond that run. Exposure is reduced by step-scoped secrets, exclusion of pull-request runs, read-only GitHub permissions, and documented rotation and emergency revocation. No credential disclosure or production exposure was established.
Retained concerns
Low · security · inferred: A copied workload private key and client ID can support authentication independently of the originating GitHub run while the key remains accepted. This extends compromise persistence compared with run-issued OIDC credentials. The documented authority includes test-project editor access; complete workload grants are not verified. Step scoping and revocation procedures reduce exposure but do not make the key run-bound.
Security review details
Security Blast Radius
inferred — A compromised credential-bearing test process could expose the private key and client ID. Reuse would inherit the workload's effective grants, including the documented test-project editor role; SPIRAL_PROJECT_ID selects the test target but does not itself constrain workload authorization. No broader production grant is established by the evidence.
Security Findings and Attack Paths
inferred — The supported attack scenario requires control of code executing with the injected credentials, or another disclosure of those credentials, followed by off-run reuse. The PR introduces the reusable key, not the existing push/manual execution routes. No malicious execution, actual disclosure, or unauthorized access was observed.
Trust Boundaries and Controls
observed — The job excludes pull-request events and other repositories, grants only contents: read, and does not directly inject the SpiralDB secrets into checkout or setup-action environments. Credentials cross into the validation and test processes through environment variables, not command-line arguments.
Resilience and Maintainability Implications
inferred — Rotation interruption before old-key removal preserves server-side overlap, while compromise recovery intentionally sacrifices job availability for containment. The procedure does not establish an automated rollback, concurrent-rotation protocol, or invalidation of already-issued access tokens; these limitations do not demonstrate a failed required invariant.
Hardening Proposals
proposed — To reduce reusable-key exposure, verify that the workload has no grants beyond the isolated test project and consider protected-environment or ref restrictions for credential-bearing runs. These are additional safeguards, not established authorization defects.
Pre-merge checks: 4
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title names the main change: the SpiralDB integration job in CI now authenticates with a workload private key instead of the previous method. The changeset matches this. The title follows the conv…
Linked Issues check
[ITL-1185] Coding requirements are implemented in .github/workflows/run-tests.yml at the reviewed head (7613f9e). (1) Authentication: the spiral-integration job sets permissions to contents: read onl…
Out of Scope Changes check
Changed files per the PR summary: .github/workflows/run-tests.yml (the spiral-integration job), RELEASING.md (setup and rotation documentation), the integration test module docstring, and docs/dev/des…
Full details: Title check
Explanation
The title names the main change: the SpiralDB integration job in CI now authenticates with a workload private key instead of the previous method. The changeset matches this. The title follows the conventional commit style, names the scope (spiral), and references the issue ITL-1185. The title is 92 characters, which is longer than ideal but still readable.
Full details: Linked Issues check
Explanation
[ITL-1185] Coding requirements are implemented in .github/workflows/run-tests.yml at the reviewed head (7613f9e). (1) Authentication: the spiral-integration job sets permissions to contents: read only. It has no id-token permission and requests no OIDC token. Its comment states the client-assertion sign-in with SPIRAL_CLIENT_ID and SPIRAL_PRIVATE_KEY. (2) Secrets: SPIRAL_CLIENT_ID and SPIRAL_PRIVATE_KEY are read only in the 'Check SpiralDB settings' step and the 'Run SpiralDB integration tests' step. They are not in the job-level env. (3) Loud failure: the check step names each missing setting (SPIRAL_CLIENT_ID, SPIRAL_PRIVATE_KEY, SPIRAL_PROJECT_ID) through ::error:: and exits 1. A Python check rejects a non-JSON-object key, and a key lacking kty, kid or d. The messages print names only, not values. (4) Documentation: RELEASING.md section 'SpiralDB integration job' (read at head) covers the editor role, key registration, both secrets, the variable, the fixed server URL, and key rotation and containment. The workflow comment also states the authentication method. The developer-owned items (credentials, secrets, grants, deletion of SPIRAL_WORKLOAD_ID and SPIRAL_SERVER_URL) are not agent work per the issue. The 'green on main' criterion is a post-merge outcome. The PR reports a manual run (workflow run 44015036993, 12 passed), but that run is not independently verified here. Minor discrepancy, not a requirement failure: the PR and RELEASING.md say the job runs on pushes to main. The unchanged on.push.branches list (main, dev, extension-type-system) and the job if condition (push or workflow_dispatch) also permit pushes to other listed branches.
Full details: Out of Scope Changes check
Explanation
Changed files per the PR summary: .github/workflows/run-tests.yml (the spiral-integration job), RELEASING.md (setup and rotation documentation), the integration test module docstring, and docs/dev/design_issues/ITL-1185-CI1.md (issue record). The workflow edits implement the ITL-1185 authentication, secret-scoping, preflight, and job-ordering changes. The job-ordering change (no needs: test) is limited to the spiral-integration job and is stated as a developer decision in the PR. The documentation changes cover the setup and rotation requirement that the issue places in scope. The PR summary reports no src/ changes, and the SpiralDB connector is untouched. No unrelated change was identified. The job-ordering rationale is not in the issue text, but it changes only the job this issue scopes.
Finishing Touches
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. View usage-based billing.
Limit details: You’ve used the included review currently available. Your 100 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.
Recent review details
Context from checks skipped due to timeout: 7
GitHub Check: CodeRabbit
GitHub Check: test (3.11)
GitHub Check: test (3.13)
GitHub Check: test (3.12)
GitHub Check: pytest / pytest (3.13)
GitHub Check: pytest / pytest (3.12)
GitHub Check: pytest / pytest (3.11)
Additional context used
Code guidelines: 1
CLAUDE.md — auto-discovered
Path-based instructions: 1
Source excerpt: Use [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) Python docstrings everywhere.
… 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 <noreply@anthropic.com>
eywalker
changed the title
ci(spiral): authenticate the SpiralDB integration job with workload client credentials (ITL-1185)
ci(spiral): authenticate the SpiralDB integration job with a workload key (ITL-1185) [on hold until after v0.3.0]
Nov 17, 2026
eywalker
changed the title
ci(spiral): authenticate the SpiralDB integration job with a workload key (ITL-1185) [on hold until after v0.3.0]
ci(spiral): authenticate the SpiralDB integration job with a workload private key (ITL-1185)
Nov 17, 2026
… 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 (7591150).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…185)
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 <noreply@anthropic.com>
CodeRabbit coverage record: the in-PR review covers the head 7613f9e8 (156c3e50..7613f9e8). It made no actionable comments and opened no inline threads.
Earlier medium concern (head 156c3e50), fixed in 7613f9e8. The rotation order (issue, replace, verify, revoke) kept a possibly exposed credential usable until a run passed. RELEASING.md now says to remove a possibly exposed key from the workload first, then add a new one.
Retained low concern (head 7613f9e8), declined with reason. A copied private key keeps signing in independently of a GitHub run until it is removed, unlike a run-issued OIDC token. This is inherent to the key-pair method. The developer chose it because the SpiralDB server rejects pyspiral's OIDC token exchange (422), and client secrets are retired. The exposure is limited by these measures:
the key goes only to the two steps that read it, through the environment;
the job never runs on pull requests;
the workload holds only the editor role on the test project;
RELEASING.md gives routine rotation and immediate removal on suspected exposure.
If a later pyspiral or spiral-sdk accepts the platform identity again, the OIDC route is preferable (noted on ITL-1185).
Posted by a Claude Code agent on behalf of @eywalker.
…gs slice (ITL-1023)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes ITL-1185
What
The
spiral-integrationjob ofRun Testsfailed on every push tomain. It signed in through a workload platform identity (SPIRAL_WORKLOAD_IDplus a GitHub OIDC token), which pyspiral sends to the API host as a token exchange. The SpiralDB server now rejects that exchange (422:grant_typetoken-exchangeunknown), so every test failed before any Orcapod code ran. SpiralDB has also retired workload client secrets.This PR moves the job to SpiralDB's current method, Sign in with a private key:
SPIRAL_CLIENT_ID(the workload id) andSPIRAL_PRIVATE_KEY(the private key as a JWK naming itskid). pyspiral signs a JWT client assertion with the key and requests a token fromhttps://auth.spiraldb.com/oauth/tokenwith theclient_credentialsgrant.id-token: writepermission is removed (contents: readstays), and the job no longer readsSPIRAL_WORKLOAD_ID.SPIRAL_PROJECT_ID(repository variable) and the hardcodedhttps://api.spiraldb.devserver URL are unchanged.SPIRAL_CLIENT_ID,SPIRAL_PRIVATE_KEYandSPIRAL_PROJECT_ID. It also refuses a key that is not a private JWK withkty,kidandd(a PEM key, for example). It prints only names, never a value.needs: testremoved; developer decision,7591150d). The job shares no artifact or output with the test jobs, and it runs only on pushes tomainand by hand. Its result now comes in minutes instead of after the full suite, and a failing test job no longer hides whether SpiralDB sign-in works. Nothing depends on the order: no job needsspiral-integration, and there is no concurrency group or job output.RELEASING.mdgains a "SpiralDB integration job" section under one-time setup: the editor grant, registering the key, both secrets, the variable, and key rotation. The test module docstring describes the CI sign-in.docs/dev/design_issues/ITL-1185-CI1.mdrecords the issue as resolved.No change under
src/, no golden file, no changelog fragment (CI only;changelog.d/README.md).The branch history keeps a first commit (
156c3e50) that used a client id and secret;505ef57ereplaced it with the key pair before anything ran, and no trace of the secret variant remains in the final diff.Verification
workflow_dispatchon this branch at7591150d, with the developer's secrets: https://github.com/metamorphic-labs/orcapod-python/actions/runs/44015036993.spiral-integrationpassed: the check step, then the integration module against the test project:***, and no key material appears in it.client_credentialswith ajwt-bearerclient assertion (ES256,kidin the header,iss=sub= workload id,aud= the token endpoint, 60 s expiry). The key pair takes precedence overSPIRAL_CLIENT_SECRETandSPIRAL_WORKLOAD_ID.bash -e. It passes with a valid key. With a missing setting, a PEM key, a JWK withoutkid, or a public-only JWK, it fails with names only.scripts/design_issues.py --checkare clean.Left for the developer (no agent touches settings)
SPIRAL_WORKLOAD_IDsecret.SPIRAL_SERVER_URLrepository variable. The workflow hardcodes thehttpsURL and does not read it.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores