Skip to content

Commit b6cf487

Browse files
gregbergegregberge
authored
Document tokenless and OIDC (#203)
1 parent 42dccf6 commit b6cf487

9 files changed

Lines changed: 219 additions & 16 deletions

File tree

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@
1919
.docusaurus
2020
.cache-loader
2121

22+
# Claude
23+
.claude/settings.local.json
24+
2225
# Misc
2326
.DS_Store
2427
.env.local
@@ -29,3 +32,4 @@
2932
npm-debug.log*
3033
yarn-debug.log*
3134
yarn-error.log*
35+

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,8 @@ jobs:
7979
matrix:
8080
shardIndex: [1, 2, 3, 4]
8181
steps:
82-
- uses: actions/checkout@v4
83-
- uses: actions/setup-node@v4
82+
- uses: actions/checkout@v6
83+
- uses: actions/setup-node@v6
8484
- run: npm ci
8585
# ---
8686
# Here you setup your repo and run your E2E tests
@@ -101,8 +101,8 @@ jobs:
101101
if: ${{ always() }}
102102
needs: ["e2e-tests"]
103103
steps:
104-
- uses: actions/checkout@v4
105-
- uses: actions/setup-node@v4
104+
- uses: actions/checkout@v6
105+
- uses: actions/setup-node@v6
106106
- run: npm ci
107107
- name: Finalize argos build
108108
env:

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ jobs:
3838
run-e2es:
3939
runs-on: ubuntu-latest
4040
steps:
41-
- uses: actions/checkout@v4
41+
- uses: actions/checkout@v6
4242

43-
- uses: actions/setup-node@v4
43+
- uses: actions/setup-node@v6
4444

4545
- name: Install dependencies
4646
run: npm ci && npx playwright install --with-deps
@@ -84,9 +84,9 @@ jobs:
8484
runs-on: ubuntu-latest
8585
8686
steps:
87-
- uses: actions/checkout@v4
87+
- uses: actions/checkout@v6
8888
89-
- uses: actions/setup-node@v4
89+
- uses: actions/setup-node@v6
9090
9191
- name: Install dependencies
9292
run: npm ci && npx playwright install --with-deps

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -102,8 +102,8 @@ For Playwright, simply set `ARGOS_SUBSET=true` in your CI job. The reporter will
102102

103103
```yml title=".github/workflows/ci.yml"
104104
steps:
105-
- uses: actions/checkout@v4
106-
- uses: actions/setup-node@v4
105+
- uses: actions/checkout@v6
106+
- uses: actions/setup-node@v6
107107
- run: npm ci
108108
- name: Run Playwright tests
109109
env:
@@ -117,8 +117,8 @@ For Cypress, set `ARGOS_SUBSET=true` in your CI job that runs Cypress and upload
117117

118118
```yml title=".github/workflows/ci.yml"
119119
steps:
120-
- uses: actions/checkout@v4
121-
- uses: actions/setup-node@v4
120+
- uses: actions/checkout@v6
121+
- uses: actions/setup-node@v6
122122
- run: npm ci
123123
- name: Run Cypress tests
124124
env:

‎docs/learn/integrations/github-oidc.mdx‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
slug: /github-oidc
3+
sidebar_label: GitHub OIDC
4+
sidebar_position: 11
5+
description: Authenticate Argos uploads from GitHub Actions using OpenID Connect (OIDC) instead of a long-lived ARGOS_TOKEN secret.
6+
---
7+
8+
# GitHub OIDC Authentication
9+
10+
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.
11+
12+
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.
13+
14+
## Why use OIDC
15+
16+
- **No long-lived secret.** Nothing to rotate, leak, or copy between repositories.
17+
- **Per-run identity.** Each token is tied to a specific repository, workflow, branch, and run. Compromise of one run cannot be replayed elsewhere.
18+
- **Least privilege.** The credential Argos issues from the OIDC exchange is scoped to uploading to a single project.
19+
- **Auditable.** GitHub signs the identity token with claims (repository, ref, workflow, actor) that Argos records on the resulting build.
20+
21+
## How it works
22+
23+
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.
24+
2. The Argos SDK detects that no `ARGOS_TOKEN` is set and fetches the OIDC token from the runner.
25+
3. The SDK sends the token to Argos with the upload request.
26+
4. Argos verifies the token's signature, issuer, audience, and claims (`repository`, `ref`, `workflow`) against the project's authentication settings.
27+
5. If the token is valid and the repository matches the Argos project, the upload is accepted.
28+
29+
The OIDC token is short-lived (minutes) and never persisted by Argos beyond what is needed to attribute the build.
30+
31+
## Enable OIDC in your Argos project
32+
33+
1. Open your project in Argos and go to **Project Settings → Authentication**.
34+
2. Enable **GitHub OIDC**.
35+
3. Save your changes.
36+
37+
Once OIDC is enabled, builds from the repository linked to the project can authenticate without `ARGOS_TOKEN`.
38+
39+
## Configure your GitHub Actions workflow
40+
41+
Two things are required on the workflow side:
42+
43+
1. Grant the workflow permission to mint an OIDC token by adding `id-token: write` to the job's `permissions` block.
44+
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.
45+
46+
```yaml title=".github/workflows/visual-tests.yml"
47+
name: Visual tests
48+
49+
on:
50+
pull_request:
51+
merge_group:
52+
53+
jobs:
54+
argos:
55+
runs-on: ubuntu-latest
56+
permissions:
57+
# Required to check out the repository and read its metadata
58+
contents: read
59+
# Required for Argos to authenticate via OIDC
60+
id-token: write
61+
# Lets Argos link the build to its pull request
62+
pull-requests: read
63+
steps:
64+
- uses: actions/checkout@v6
65+
- uses: actions/setup-node@v6
66+
- run: npm ci
67+
- run: npm run test:e2e
68+
# Note: no ARGOS_TOKEN — the SDK uses OIDC automatically
69+
```
70+
71+
:::warning
72+
73+
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.
74+
75+
:::
76+
77+
:::note
78+
79+
`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).
80+
81+
:::
82+
83+
## Troubleshooting
84+
85+
**`Unable to get OIDC token` / 403 from the OIDC endpoint.** The job is missing `id-token: write`. Add it to the `permissions` block.
86+
87+
**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).
88+
89+
**`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.
90+
91+
**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.
92+
93+
## Prefer OIDC over tokenless authentication
94+
95+
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.
96+
97+
**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.
98+
99+
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.
100+
101+
To switch from tokenless to OIDC on the runs where it is available:
102+
103+
1. Enable **GitHub OIDC** in your Argos project's authentication settings.
104+
2. Add `id-token: write` to the workflow permissions.
105+
106+
No code change is required in your tests — the SDK picks up OIDC automatically when it is available and no token is set.
107+
108+
## Further reading
109+
110+
- [GitHub: About security hardening with OpenID Connect](https://docs.github.com/en/actions/reference/security/oidc)
111+
- [GitHub: Assigning permissions to jobs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token)
112+
- [Argos GitHub Integration](/github)

‎docs/learn/integrations/github-tokenless.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
slug: /github-tokenless
3+
sidebar_label: GitHub Tokenless
4+
sidebar_position: 12
5+
description: Authenticate Argos uploads from GitHub Actions without an ARGOS_TOKEN by letting Argos verify the run against GitHub's workflow API.
6+
---
7+
8+
# GitHub Tokenless Authentication
9+
10+
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.
11+
12+
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.
13+
14+
:::tip
15+
16+
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.
17+
18+
:::
19+
20+
## When tokenless is used
21+
22+
The SDK picks an authentication method in this order:
23+
24+
1. **`ARGOS_TOKEN`** is set → use the token.
25+
2. **OIDC is enabled** (`id-token: write` permission granted and Argos project configured for OIDC) → use OIDC.
26+
3. **Neither is available** → fall back to tokenless authentication.
27+
28+
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).
29+
30+
## How it works
31+
32+
1. The Argos SDK detects that no `ARGOS_TOKEN` is set and no OIDC token is available.
33+
2. The SDK sends an upload request to Argos with the GitHub-provided context: repository, commit SHA, branch, and workflow run ID.
34+
3. Argos calls the GitHub API to look up workflow runs for that repository at that commit and branch.
35+
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.
36+
5. The SDK uses that short-lived token to complete the upload.
37+
38+
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.
39+
40+
## Use cases
41+
42+
- **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.
43+
- **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.
44+
- **Quick setup.** You can connect a repository to Argos and have uploads work from GitHub Actions without configuring anything in the workflow.
45+
46+
## Configure your GitHub Actions workflow
47+
48+
Tokenless requires no special configuration — just leave `ARGOS_TOKEN` unset and do not grant `id-token: write`:
49+
50+
```yaml title=".github/workflows/visual-tests.yml"
51+
name: Visual tests
52+
53+
on:
54+
pull_request:
55+
merge_group:
56+
57+
jobs:
58+
argos:
59+
runs-on: ubuntu-latest
60+
steps:
61+
- uses: actions/checkout@v6
62+
- uses: actions/setup-node@v6
63+
- run: npm ci
64+
- run: npm run test:e2e
65+
# No ARGOS_TOKEN — the SDK falls back to tokenless authentication
66+
```
67+
68+
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.
69+
70+
## Limitations
71+
72+
- **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`.
73+
- **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.
74+
- **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.
75+
76+
## Troubleshooting
77+
78+
**`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.
79+
80+
**`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.
81+
82+
**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).
83+
84+
## Further reading
85+
86+
- [GitHub OIDC authentication](/github-oidc) — the more secure option, preferred where available.
87+
- [Argos GitHub Integration](/github)

‎docs/learn/integrations/github.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Argos needs the following permissions to operate:
5454
- **Contents** — used to find a common commit ancestor between branches
5555
- **Statuses** — used to add statuses to commits
5656
- **Pull requests** — used to add comments in pull requests
57-
- **Actions** — used to allow tokenless authentication
57+
- **Actions** — used to re-run an individual GitHub Actions workflow run when a check is retried from Argos
5858

5959
We take your security and privacy seriously. If you have any concerns or questions, please [contact us](https://argos-ci.com/contact).
6060

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,8 +94,8 @@ jobs:
9494
runs-on: ubuntu-latest
9595
timeout-minutes: 30
9696
steps:
97-
- uses: actions/checkout@v4
98-
- uses: actions/setup-node@v4
97+
- uses: actions/checkout@v6
98+
- uses: actions/setup-node@v6
9999

100100
- name: Install dependencies
101101
run: npm ci

‎docs/sdks/cli.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ For local review commands, sign in once with the browser-based login flow:
3737

3838
:::warning
3939

40-
Do not use `argos login` in CI. CI uploads should use `ARGOS_TOKEN`, `--token`, or tokenless authentication when supported by your CI integration.
40+
Do not use `argos login` in CI. CI uploads should use `ARGOS_TOKEN`, `--token`, or [GitHub OIDC authentication](/github-oidc).
4141

4242
:::
4343

0 commit comments

Comments
 (0)