Document tokenless and OIDC

.gitignore

@@ -19,6 +19,9 @@
 .docusaurus
 .cache-loader
 
+# Claude
+.claude/settings.local.json
+
 # Misc
 .DS_Store
 .env.local
@@ -29,3 +32,4 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+

docs/learn/guides/ci-pipelines/parallel-testing.mdx

@@ -79,8 +79,8 @@ jobs:
       matrix:
         shardIndex: [1, 2, 3, 4]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
       - run: npm ci
       # ---
       # Here you setup your repo and run your E2E tests
@@ -101,8 +101,8 @@ jobs:
     if: ${{ always() }}
     needs: ["e2e-tests"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
       - run: npm ci
       - name: Finalize argos build
         env:

docs/learn/guides/ci-pipelines/run-on-preview-deployment.mdx

@@ -38,9 +38,9 @@ jobs:
   run-e2es:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
 
       - name: Install dependencies
         run: npm ci && npx playwright install --with-deps
@@ -84,9 +84,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
 
       - name: Install dependencies
         run: npm ci && npx playwright install --with-deps

docs/learn/guides/ci-pipelines/subset-builds.mdx

@@ -102,8 +102,8 @@ For Playwright, simply set `ARGOS_SUBSET=true` in your CI job. The reporter will
 
 ```yml title=".github/workflows/ci.yml"
 steps:
-  - uses: actions/checkout@v4
-  - uses: actions/setup-node@v4
+  - uses: actions/checkout@v6
+  - uses: actions/setup-node@v6
   - run: npm ci
   - name: Run Playwright tests
     env:
@@ -117,8 +117,8 @@ For Cypress, set `ARGOS_SUBSET=true` in your CI job that runs Cypress and upload
 
 ```yml title=".github/workflows/ci.yml"
 steps:
-  - uses: actions/checkout@v4
-  - uses: actions/setup-node@v4
+  - uses: actions/checkout@v6
+  - uses: actions/setup-node@v6
   - run: npm ci
   - name: Run Cypress tests
     env:

docs/learn/integrations/github-oidc.mdx

@@ -0,0 +1,112 @@
+---
+slug: /github-oidc
+sidebar_label: GitHub OIDC
+sidebar_position: 11
+description: Authenticate Argos uploads from GitHub Actions using OpenID Connect (OIDC) instead of a long-lived ARGOS_TOKEN secret.
+---
+
+# GitHub OIDC Authentication
+
+Authenticate the Argos SDK from GitHub Actions using [OpenID Connect (OIDC)](https://docs.github.com/en/actions/reference/security/oidc) instead of storing a long-lived `ARGOS_TOKEN` secret in your repository.
+
+With OIDC, each workflow run receives a short-lived identity token signed by GitHub. Argos verifies that token against the repository and workflow you have allowed, then issues a temporary upload credential scoped to that build. No secret is ever stored in GitHub.
+
+## Why use OIDC
+
+- **No long-lived secret.** Nothing to rotate, leak, or copy between repositories.
+- **Per-run identity.** Each token is tied to a specific repository, workflow, branch, and run. Compromise of one run cannot be replayed elsewhere.
+- **Least privilege.** The credential Argos issues from the OIDC exchange is scoped to uploading to a single project.
+- **Auditable.** GitHub signs the identity token with claims (repository, ref, workflow, actor) that Argos records on the resulting build.
+
+## How it works
+
+1. GitHub Actions requests an OIDC identity token from GitHub's OIDC provider for the current job. This requires the `id-token: write` workflow permission.
+2. The Argos SDK detects that no `ARGOS_TOKEN` is set and fetches the OIDC token from the runner.
+3. The SDK sends the token to Argos with the upload request.
+4. Argos verifies the token's signature, issuer, audience, and claims (`repository`, `ref`, `workflow`) against the project's authentication settings.
+5. If the token is valid and the repository matches the Argos project, the upload is accepted.
+
+The OIDC token is short-lived (minutes) and never persisted by Argos beyond what is needed to attribute the build.
+
+## Enable OIDC in your Argos project
+
+1. Open your project in Argos and go to **Project Settings → Authentication**.
+2. Enable **GitHub OIDC**.
+3. Save your changes.
+
+Once OIDC is enabled, builds from the repository linked to the project can authenticate without `ARGOS_TOKEN`.
+
+## Configure your GitHub Actions workflow
+
+Two things are required on the workflow side:
+
+1. Grant the workflow permission to mint an OIDC token by adding `id-token: write` to the job's `permissions` block.
+2. **Remove** `ARGOS_TOKEN` from the job environment. The SDK uses OIDC only when no token is provided — if `ARGOS_TOKEN` is set, it takes precedence.
+
+```yaml title=".github/workflows/visual-tests.yml"
+name: Visual tests
+
+on:
+  pull_request:
+  merge_group:
+
+jobs:
+  argos:
+    runs-on: ubuntu-latest
+    permissions:
+      # Required to check out the repository and read its metadata
+      contents: read
+      # Required for Argos to authenticate via OIDC
+      id-token: write
+      # Lets Argos link the build to its pull request
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+      - run: npm ci
+      - run: npm run test:e2e
+        # Note: no ARGOS_TOKEN — the SDK uses OIDC automatically
+```
+
+:::warning
+
+If `ARGOS_TOKEN` is defined (as a repository, environment, or organization secret exposed to the job), the SDK will use it and skip OIDC entirely. Remove it from the job to enable OIDC.
+
+:::
+
+:::note
+
+`id-token: write` must be set on the job (or at the workflow level). Adding it only to the `permissions` block of another job does not grant it to your Argos job. See [GitHub's documentation on `id-token` permissions](https://docs.github.com/en/actions/reference/security/oidc#adding-permissions-settings).
+
+:::
+
+## Troubleshooting
+
+**`Unable to get OIDC token` / 403 from the OIDC endpoint.** The job is missing `id-token: write`. Add it to the `permissions` block.
+
+**Argos still uses `ARGOS_TOKEN`.** A secret is being injected into the job. Search your workflow, environments, and reusable workflows for `ARGOS_TOKEN` and remove it. You can confirm by printing `echo "${ARGOS_TOKEN:+set}${ARGOS_TOKEN:-unset}"` in a step (the value itself is masked).
+
+**`Repository does not match the Argos project`.** The repository that ran the workflow is not the one linked to the Argos project. Run the workflow from the linked repository, or update the project's connected repository in Argos.
+
+**OIDC is not used on forked pull requests.** GitHub does not issue OIDC tokens to workflows triggered from forks for security reasons. For PRs from forks, the Argos SDK automatically falls back to [tokenless authentication](/github-tokenless), which is designed to work in that context.
+
+## Prefer OIDC over tokenless authentication
+
+Argos SDKs also support a [**tokenless**](/github-tokenless) mode that authenticates GitHub Actions runs without an `ARGOS_TOKEN` and without OIDC, by looking up the workflow run on GitHub from its commit and branch.
+
+**If OIDC is available in your setup, prefer it over tokenless authentication.** OIDC is more secure because every upload is backed by a short-lived token signed by GitHub's OIDC provider, which Argos cryptographically verifies.
+
+Tokenless authentication remains useful where OIDC cannot be used — most notably for **pull requests from forked repositories**, where GitHub does not issue OIDC tokens. The SDK falls back to tokenless automatically in those cases, so a single workflow can use OIDC for internal PRs and tokenless for fork PRs without any extra configuration.
+
+To switch from tokenless to OIDC on the runs where it is available:
+
+1. Enable **GitHub OIDC** in your Argos project's authentication settings.
+2. Add `id-token: write` to the workflow permissions.
+
+No code change is required in your tests — the SDK picks up OIDC automatically when it is available and no token is set.
+
+## Further reading
+
+- [GitHub: About security hardening with OpenID Connect](https://docs.github.com/en/actions/reference/security/oidc)
+- [GitHub: Assigning permissions to jobs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token)
+- [Argos GitHub Integration](/github)

docs/learn/integrations/github-tokenless.mdx

@@ -0,0 +1,87 @@
+---
+slug: /github-tokenless
+sidebar_label: GitHub Tokenless
+sidebar_position: 12
+description: Authenticate Argos uploads from GitHub Actions without an ARGOS_TOKEN by letting Argos verify the run against GitHub's workflow API.
+---
+
+# GitHub Tokenless Authentication
+
+Tokenless authentication lets the Argos SDK upload builds from GitHub Actions without an `ARGOS_TOKEN` secret and without OIDC. Argos verifies the run by looking it up on GitHub from the commit and branch the SDK reports.
+
+It is the default fallback the Argos SDK uses when neither `ARGOS_TOKEN` nor [OIDC](/github-oidc) is available — most importantly, on **pull requests from forked repositories**, where GitHub does not issue OIDC tokens.
+
+:::tip
+
+If your workflow can use [GitHub OIDC](/github-oidc), prefer it. OIDC is cryptographically signed by GitHub and is the strongest form of CI authentication Argos supports. Tokenless is the right choice when OIDC cannot be used.
+
+:::
+
+## When tokenless is used
+
+The SDK picks an authentication method in this order:
+
+1. **`ARGOS_TOKEN`** is set → use the token.
+2. **OIDC is enabled** (`id-token: write` permission granted and Argos project configured for OIDC) → use OIDC.
+3. **Neither is available** → fall back to tokenless authentication.
+
+So tokenless kicks in when you have not configured a token *and* the workflow has not been granted `id-token: write` (or OIDC has not been enabled in your Argos project settings).
+
+## How it works
+
+1. The Argos SDK detects that no `ARGOS_TOKEN` is set and no OIDC token is available.
+2. The SDK sends an upload request to Argos with the GitHub-provided context: repository, commit SHA, branch, and workflow run ID.
+3. Argos calls the GitHub API to look up workflow runs for that repository at that commit and branch.
+4. If Argos finds a workflow run that is **in progress** and matches the context the SDK reported, it issues a **short-lived token** scoped to that run and to the project.
+5. The SDK uses that short-lived token to complete the upload.
+
+The verification rests on a simple invariant: only the actual workflow run on GitHub can produce an upload whose context matches a run GitHub reports as in progress. If the run is not found, is not in progress, or doesn't match the repository linked to the Argos project, the upload is rejected.
+
+## Use cases
+
+- **Forked pull requests.** GitHub blocks OIDC and secrets on workflows triggered from forks. Tokenless authentication still works because it relies on the GitHub API rather than on a token injected into the runner.
+- **Public repositories without configured secrets.** New contributors can open a PR and have visual tests run end-to-end without a maintainer needing to provision a token.
+- **Quick setup.** You can connect a repository to Argos and have uploads work from GitHub Actions without configuring anything in the workflow.
+
+## Configure your GitHub Actions workflow
+
+Tokenless requires no special configuration — just leave `ARGOS_TOKEN` unset and do not grant `id-token: write`:
+
+```yaml title=".github/workflows/visual-tests.yml"
+name: Visual tests
+
+on:
+  pull_request:
+  merge_group:
+
+jobs:
+  argos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+      - run: npm ci
+      - run: npm run test:e2e
+        # No ARGOS_TOKEN — the SDK falls back to tokenless authentication
+```
+
+If you want OIDC for internal PRs *and* tokenless for fork PRs in the same workflow, add `id-token: write` to the job's `permissions` block. The SDK uses OIDC when GitHub issues a token and automatically falls back to tokenless on fork PRs where it doesn't.
+
+## Limitations
+
+- **GitHub Actions only.** Tokenless authentication relies on the GitHub workflow run lookup. It does not work outside GitHub Actions — for other CI providers, use `ARGOS_TOKEN`.
+- **The workflow run must be visible to GitHub.** If the SDK runs in a context where GitHub does not report the run (for example, a self-hosted action that runs outside the standard workflow runner), tokenless cannot verify it.
+- **Weaker proof than OIDC.** Tokenless verifies that a workflow with the same commit and branch is in progress; OIDC verifies a signed token from GitHub. Prefer OIDC where it is available.
+
+## Troubleshooting
+
+**`No matching workflow run found`.** Argos could not find an in-progress workflow run on GitHub matching the commit and branch the SDK reported. Check that the repository linked to the Argos project matches the one running the workflow, and that the workflow is still in progress when the upload runs.
+
+**`Repository does not match the Argos project`.** The repository running the workflow is not the one linked to the Argos project. Update the project's connected repository in Argos, or run the workflow from the linked repository.
+
+**Uploads work but are missing pull request metadata.** Tokenless authenticates the upload but does not by itself link the build to a pull request. Pass `GITHUB_TOKEN` in the job environment so the SDK can resolve the PR — see [Running without `GITHUB_TOKEN`](/run-on-preview-deployment#running-without-github_token).
+
+## Further reading
+
+- [GitHub OIDC authentication](/github-oidc) — the more secure option, preferred where available.
+- [Argos GitHub Integration](/github)

docs/learn/integrations/github.mdx

@@ -54,7 +54,7 @@ Argos needs the following permissions to operate:
 - **Contents** — used to find a common commit ancestor between branches
 - **Statuses** — used to add statuses to commits
 - **Pull requests** — used to add comments in pull requests
-- **Actions** — used to allow tokenless authentication
+- **Actions** — used to re-run an individual GitHub Actions workflow run when a check is retried from Argos
 
 We take your security and privacy seriously. If you have any concerns or questions, please [contact us](https://argos-ci.com/contact).
 

docs/quickstart/storybook/storybook-test-runner.mdx

@@ -94,8 +94,8 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
 
       - name: Install dependencies
         run: npm ci

docs/sdks/cli.mdx

@@ -37,7 +37,7 @@ For local review commands, sign in once with the browser-based login flow:
 
 :::warning
 
-Do not use `argos login` in CI. CI uploads should use `ARGOS_TOKEN`, `--token`, or tokenless authentication when supported by your CI integration.
+Do not use `argos login` in CI. CI uploads should use `ARGOS_TOKEN`, `--token`, or [GitHub OIDC authentication](/github-oidc).
 
 :::