> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/guides/record-key/record-from-ci-with-oidc.md).

# Record from CI with OIDC

Record test runs to Currents from GitHub Actions, GitLab.com, CircleCI, Buildkite or Bitbucket Pipelines without storing a record key, using the CI provider's OIDC token

A CI job can record runs to Currents without a stored record key. The reporter exchanges the job's OIDC token (OpenID Connect identity token) for a short-lived record key. There is no record key to store in CI secrets and none to rotate.

The exchange follows OAuth 2.0 Token Exchange ([RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693)), and the revoke follows OAuth 2.0 Token Revocation ([RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009)).

## Prerequisites

* A Currents project and its project ID. See [Quick Start](/getting-started/your-first-playwright-run.md).
* Organization admin access, to create a trust policy.
* A CI provider that Currents accepts: GitHub Actions, GitLab.com, CircleCI, Buildkite or Bitbucket Pipelines. A self-hosted Currents can also accept self-managed GitLab and GitHub Enterprise Server, see [Self-hosted Currents](#self-hosted-currents).
* One of these clients:
  * `@currents/playwright` 2.8.0 or later
  * `@currents/cmd` 3.1.0 or later, for the commands that take a record key. Commands that take only an API key still need one, see [Credentials](/resources/reporters/currents-cmd.md#credentials).
  * [`cancel-run-gh-action`](#cancel-run-gh-action) 1.2.0 or later (`@v1`)
  * [`playwright-last-failed`](#playwright-last-failed) 2.2.0 or later (`@v2`)

## Create a trust policy

A trust policy tells Currents which CI jobs may get a record key for your organization. It names a CI provider and an owner, such as a GitHub organization, and optionally one project of that owner.

{% stepper %}
{% step %}
In the organization menu of the dashboard, open **API & Record Keys**, then the **OIDC trust policies** section. Only organization admins see the section.

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2Fgit-blob-33e7305dd26d356e343b8052d49e30833b8e8955%2Foidc-trust-policies-section.png?alt=media" alt="The OIDC trust policies section of API &#x26; Record Keys: a Create trust policy button, and a list of trusted owners and projects with their CI provider, two of them marked Never used" width="720"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Select **Create trust policy**, and pick the **CI provider**: GitHub, GitLab.com, CircleCI, Buildkite or Bitbucket.

On a self-hosted Currents that lists self-managed instances, a **Server** menu appears for GitHub and GitLab. Pick `github.com`, `gitlab.com` or the host of the instance.
{% endstep %}

{% step %}
Enter the owner. To limit the policy to one project, also enter the project. Leave the project empty to trust every project of the owner.

* GitHub: enter **GitHub organization or user** and **Repository (optional)** by name. Currents looks them up on GitHub, and finds public repositories only. For a private repository, select **Enter the IDs myself (private repositories)** and enter the **Owner ID** (`repository_owner_id`) and, if you named a repository, the **Repository ID** (`repository_id`). The help under each field shows the `gh api` command that prints the ID.
* GitHub Enterprise Server: enter **GitHub owner ID** and **GitHub repository ID (optional)**.
* GitLab.com, CircleCI, Buildkite and Bitbucket: enter the IDs. The help under each field says where to find them. **Owner name** and **Project name** are optional and only label the policy in the list.
  {% endstep %}

{% step %}
Optional: enter **Maximum token age (minutes)**, a whole number from 1 to 1440. Currents then refuses a token issued longer ago than this, counted from the `iat` claim of the token. A short limit reduces how long a token that leaks from a job log stays useful. Leave the field empty for no limit.
{% endstep %}

{% step %}
Select **Create**.

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2Fgit-blob-c670c18d67d4f0dad6fed2cecf22469dee2bcc7b%2Foidc-create-trust-policy-dialog.png?alt=media" alt="The Create trust policy dialog for GitHub, with the organization acme and the repository web entered, the Enter the IDs myself checkbox, an empty Maximum token age field, and the Create button" width="560"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

Organization admins get an email when a policy is created or removed.

### Which IDs Currents matches

Currents matches the IDs that the CI provider puts in the token, not the names. A renamed repository keeps its ID and still matches. A new repository created under an old name has a new ID and does not match.

| CI provider         | Owner                       | Project (optional) | IDs are |
| ------------------- | --------------------------- | ------------------ | ------- |
| GitHub Actions      | GitHub organization or user | Repository         | numbers |
| GitLab.com          | GitLab namespace            | Project            | numbers |
| CircleCI            | CircleCI organization       | Project            | UUIDs   |
| Buildkite           | Buildkite organization      | Pipeline           | UUIDs   |
| Bitbucket Pipelines | Bitbucket workspace         | Repository         | UUIDs   |

* A GitLab namespace is the group or user that directly holds the project. A policy for a group does not cover the projects in its subgroups. A project moved to another namespace stops matching.
* When an owner policy and a project policy both match a job, Currents uses the project policy.
* A job that no policy matches fails with `No trust policy` and prints the IDs to enter. See [No trust policy for the repository](#no-trust-policy-for-the-repository).
* CircleCI Server and Bitbucket Data Center are not supported.

### View or remove a policy

The section lists each policy with its owner or project and its CI provider. **Never used** marks a policy that no job has used yet: its names are the ones an admin typed, and the names from the first job's token replace them.

Select a policy to see its details. To remove it, select **Stop trusting**. Currents then revokes every record key issued through the policy, and jobs that are running lose their key.

<figure><img src="https://3745692499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqmFDEiUa9mr11LUlxDnt%2Fuploads%2Fgit-blob-73511fa17c467dc7c0aebcc02157b777e70e10a6%2Foidc-trust-policy-details.png?alt=media" alt="Trust policy details for acme/web: provider GitHub, owner ID, project ID, applies to this project only, token age up to 30 minutes, who added it and when, and the Stop trusting button" width="560"><figcaption></figcaption></figure>

## Configure the CI job

These steps apply to every CI provider:

1. Remove `CURRENTS_RECORD_KEY` and any `--key` or `recordKey` value from the job. A configured record key takes priority, and the reporter does not request a token while one is set. The same holds for an API key on a `currents` command that accepts one.
2. Set the project ID in `CURRENTS_PROJECT_ID` or `--project-id`. With `@currents/playwright`, the `projectId` reporter option also works.
3. Give the job an OIDC token with the audience `currents:record-key`. The sections below show how for each provider.

The examples run `pwc`. With plain `playwright test`, OIDC needs Playwright 1.62 or later, so that the workers get the record key. On an older Playwright, run `pwc`.

In the examples, replace `YOUR_PLAYWRIGHT_VERSION` with the Playwright image tag of your project, and `YOUR_PROJECT_ID` with the Currents project ID.

### GitHub Actions

Add `permissions: id-token: write` to the workflow or the job. The reporter requests the token itself.

```yaml
name: Playwright Tests
on:
  pull_request:
    branches: [main]
permissions:
  id-token: write
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.x"
      - run: npm ci
      - name: Playwright Tests
        env:
          CURRENTS_PROJECT_ID: ${{ vars.CURRENTS_PROJECT_ID }}
        run: npx pwc
```

GitHub normally gives no OIDC token to a pull request from a fork, so that job cannot record. Currents does not check whether a job comes from a fork: it accepts any job whose repository matches a trust policy. Record only from workflows that do not run code from forks.

### GitLab.com

Add an `id_tokens` entry named `CURRENTS_OIDC_TOKEN` to the job, with `aud: currents:record-key`.

```yaml
playwright:
  image: mcr.microsoft.com/playwright:YOUR_PLAYWRIGHT_VERSION
  id_tokens:
    CURRENTS_OIDC_TOKEN:
      aud: currents:record-key
  script:
    - npm ci
    - npx pwc --project-id YOUR_PROJECT_ID
```

### CircleCI

Request a token with the audience `currents:record-key`, and export it as `CURRENTS_OIDC_TOKEN` in the step that runs the tests. The job needs a CircleCI CLI that supports `circleci run oidc get --aud`.

```yaml
version: 2.1
jobs:
  test:
    docker:
      - image: mcr.microsoft.com/playwright:YOUR_PLAYWRIGHT_VERSION
    steps:
      - checkout
      - run: npm ci
      - run:
          name: Playwright Tests
          command: |
            export CURRENTS_OIDC_TOKEN=$(circleci run oidc get --aud currents:record-key)
            npx pwc --project-id YOUR_PROJECT_ID
workflows:
  test:
    jobs:
      - test
```

Do not use `CIRCLE_OIDC_TOKEN_V2` or `CIRCLE_OIDC_TOKEN_V3`. Their audience is the CircleCI organization ID, a job cannot change it, and Currents refuses them.

### Buildkite

Request a token with the audience `currents:record-key`, and export it as `CURRENTS_OIDC_TOKEN`. `buildkite-agent` must be on the `PATH` of the step.

```yaml
steps:
  - label: "Playwright Tests"
    command:
      - npm ci
      - export CURRENTS_OIDC_TOKEN=$(buildkite-agent oidc request-token --audience currents:record-key)
      - npx pwc --project-id YOUR_PROJECT_ID
```

Without `--audience`, the audience is `https://buildkite.com/<organization slug>`, and Currents refuses the token.

### Bitbucket Pipelines

Add `currents:record-key` under `oidc: audiences:` of the step, and copy the step's token to `CURRENTS_OIDC_TOKEN`. To set the audience for every step, add `oidc: audiences:` under `options:` instead.

```yaml
pipelines:
  default:
    - step:
        name: Playwright Tests
        image: mcr.microsoft.com/playwright:YOUR_PLAYWRIGHT_VERSION
        oidc:
          audiences:
            - currents:record-key
        script:
          - npm ci
          - export CURRENTS_OIDC_TOKEN="$BITBUCKET_STEP_OIDC_TOKEN"
          - npx pwc --project-id YOUR_PROJECT_ID
```

Currents accepts the token when `currents:record-key` is one of its audiences.

### Pass the token yourself

On any supported provider, you can get the token yourself and give it to the reporter. The reporter uses the first token it finds:

1. The `oidcToken` reporter option of `@currents/playwright`, or the `--oidc-token` option of the `currents` CLI.
2. The `CURRENTS_OIDC_TOKEN` environment variable.
3. On GitHub Actions, a token the reporter requests itself.

Prefer `CURRENTS_OIDC_TOKEN` to `--oidc-token`: command-line options show in the process list and in logs that echo commands. Keep the token and the record key out of job logs.

### Currents GitHub Actions

#### cancel-run-gh-action

[`cancel-run-gh-action`](https://github.com/currents-dev/cancel-run-gh-action) 1.2.0 or later (`@v1`) cancels a Currents run when the workflow is cancelled. With no `record-key` input, no `api-token` input and no `CURRENTS_RECORD_KEY`, it gets a record key from the job's OIDC token.

The action needs:

* `permissions: id-token: write`
* `project-id` or `CURRENTS_PROJECT_ID`
* the run: `ci-build-id` or `CURRENTS_CI_BUILD_ID`, or `run-id`

```yaml
permissions:
  id-token: write
  contents: read

env:
  CURRENTS_PROJECT_ID: YOUR_PROJECT_ID
  CURRENTS_CI_BUILD_ID: ${{ github.run_id }}-${{ github.run_attempt }}

steps:
  - name: Cancel the Currents run
    if: ${{ cancelled() }}
    uses: currents-dev/cancel-run-gh-action@v1
```

The [action's README](https://github.com/currents-dev/cancel-run-gh-action#inputs) lists every input.

#### playwright-last-failed

[`playwright-last-failed`](https://github.com/currents-dev/playwright-last-failed) 2.2.0 or later (`@v2`) reruns the tests that failed in the last run. Without the `key` input or `CURRENTS_RECORD_KEY`, it gets a record key from the job's OIDC token. It needs `permissions: id-token: write` and the `project-id` input or `CURRENTS_PROJECT_ID`.

The action installs the latest `@currents/cmd` from npm, which has to be 3.1.0 or later. The API mode (`or8n` and `use-api`) still needs `api-key`.

```yaml
permissions:
  id-token: write
  contents: read

steps:
  - name: Playwright Last Failed
    id: last-failed
    uses: currents-dev/playwright-last-failed@v2
    with:
      project-id: YOUR_PROJECT_ID
      matrix-index: ${{ matrix.shard }}
      matrix-total: ${{ strategy.job-total }}
```

## Check that it works

At the start of the run, the reporter prints where the record key came from and when it expires. `pwc` and the Playwright reporter print:

```
Using a record key from GitHub Actions OIDC, valid until 2026-11-14T08:00:00.000Z
```

The `currents` CLI prints:

```
Using a record key from the GitHub Actions OIDC token, valid until 2026-11-14T08:00:00.000Z
```

With a token from `CURRENTS_OIDC_TOKEN` or the token options, the source names that variable or option. Then open the run in the dashboard.

## Troubleshooting

A failed exchange prints a prefix and then the message from Currents. `pwc` and the Playwright reporter print `Could not get a record key from <source>: <message>`. The `currents` CLI prints `Could not exchange the <source> for a record key: <message>`. The examples below show the `pwc` prefix.

### No trust policy for the repository

```
Could not get a record key from GitHub Actions OIDC: No trust policy for GitHub Actions repository "my-org/my-repo" (repository ID 123456789, owner ID 987654321) for the Currents project "YOUR_PROJECT_ID". An admin of the organization that owns the project can add one in the dashboard, under Organization → API and Record Keys.
```

No trust policy matches the job. [Create a trust policy](#create-a-trust-policy) with the IDs the message prints. The policy must be in the organization that owns the project ID the job sends.

### Token is older than the trust policy allows

```
The OIDC token was issued more than 10 minutes ago, which is older than the trust policy allows. Request a new token in the job that calls Currents.
```

The token is older than the **Maximum token age (minutes)** of the policy. Request the token in the step that runs the tests, or raise the limit on the policy.

### Wrong audience

```
The OIDC token audience must be "currents:record-key". Request the token with audience currents:record-key.
```

The token was issued for another audience. Request it with the audience the message names, as shown for your provider in [Configure the CI job](#configure-the-ci-job). A self-hosted Currents has its own audience, see [Self-hosted Currents](#self-hosted-currents).

### Provider not supported

```
The OIDC token issuer "https://gitlab.example.com" is not supported. Supported CI providers: GitHub Actions, GitLab.com, CircleCI, Buildkite, Bitbucket Pipelines.
```

Currents does not accept tokens from this issuer. Currents cloud accepts only the providers in the message. On a self-hosted Currents, the operator can add a self-managed GitLab or GitHub Enterprise Server, see [Self-managed GitLab and GitHub Enterprise Server](#self-managed-gitlab-and-github-enterprise-server). Otherwise, use a record key.

### Organization is inactive

```
The Currents organization that trusts GitHub Actions repository "my-org/my-repo" is inactive.
```

The organization that owns the policy is inactive. Contact support.

### Project ID is not set

`pwc` and the Playwright reporter:

```
Could not get a record key from GitHub Actions OIDC: the project ID is not set. Use the projectId option, CURRENTS_PROJECT_ID or --project-id
```

The `currents` CLI:

```
Project ID is required to get a record key from an OIDC token: pass --project-id or set CURRENTS_PROJECT_ID
```

Set the project ID in the job.

### Record key is required

`pwc` and the Playwright reporter:

```
Record Key is required for Currents Reporter.
```

The `currents` CLI:

```
Record key is required: pass --key or set CURRENTS_RECORD_KEY. Without a stored record key, a CI job can use its OIDC token: set `permissions: id-token: write` on GitHub Actions, or on any other CI put a token in --oidc-token or CURRENTS_OIDC_TOKEN with currents:record-key as its audience (for GitLab `id_tokens`: `aud: currents:record-key`). Staging and on-prem installs use their own audience: set CURRENTS_OIDC_AUDIENCE to its value. https://docs.currents.dev
```

The reporter found neither a record key nor an OIDC token. Both messages go on with a hint on how to give the job a token.

* GitHub Actions: add `permissions: id-token: write` to the workflow or job. A pull request from a fork normally gets no token.
* GitLab.com: add the `id_tokens` entry `CURRENTS_OIDC_TOKEN` to the job.
* CircleCI, Buildkite and Bitbucket Pipelines: export `CURRENTS_OIDC_TOKEN` as shown in [Configure the CI job](#configure-the-ci-job).
* Plain `playwright test` on Playwright older than 1.62: run `pwc` instead.

### OIDC exchange is not available

```
Could not get a record key from GitHub Actions OIDC: Exchanging an OIDC token for a record key is not enabled on this Currents deployment.
```

The Currents server has the exchange turned off. On a self-hosted Currents, the operator turns it on, see [Self-hosted Currents](#self-hosted-currents). Use a record key until then.

```
Could not get a record key from GitHub Actions OIDC: Exchanging an OIDC token for a record key is enabled on this Currents deployment but not configured: it has no OIDC_TOKEN_AUDIENCE.
```

The exchange is on, but `OIDC_TOKEN_AUDIENCE` is not set. Ask the operator to set it.

### Could not revoke the record key

```
Could not revoke the record key from OIDC (<reason>). It expires on its own.
```

`cancel-run-gh-action` logs this warning when it cannot revoke the record key it got. The step does not fail. The record key expires 6 hours after it was issued.

## Self-hosted Currents

A self-hosted Currents has the exchange turned off. The operator turns it on with these settings:

* `OIDC_TOKEN_EXCHANGE_ENABLED=true` turns the exchange on (director).
* `OIDC_TOKEN_AUDIENCE` is the audience that tokens must have (director). It is required when the exchange is on and has no default. Choose a name for the installation, such as `currents:record-key:acme`. Do not use `currents:record-key`: Currents would then accept tokens made for Currents cloud.
* `OIDC_TRUST_FORWARDED_FOR=true` only when a proxy in front of the director appends the client address to `X-Forwarded-For` and drops any value the caller sent (director). Without it, the director counts requests by the address of the connection.
* `OIDC_EXTRA_ISSUERS` lists self-managed GitLab and GitHub Enterprise Server instances (director and API). See [Self-managed GitLab and GitHub Enterprise Server](#self-managed-gitlab-and-github-enterprise-server).

With the Helm chart, the values are `currents.oidcTokenExchange.enabled`, `audience`, `trustForwardedFor` and `extraIssuers`. See the [Docker Compose](https://currents-dev.github.io/docker/configuration.html) and [Kubernetes](https://currents-dev.github.io/helm-charts/docs/) documentation.

The director checks each token against the public signing keys of its issuer, which it fetches over https. For the cloud CI providers, the director needs internet access. For the instances in `OIDC_EXTRA_ISSUERS`, it needs access to those hosts only.

The scheduler creates the MongoDB indexes that the exchange needs when it starts.

In the CI jobs that record to the installation, set `CURRENTS_API_URL` to the director of the installation. Without it, the reporter and the `currents` CLI send the token to Currents cloud, and the exchange fails. `currents` commands that also call the REST API need `CURRENTS_REST_API_URL`, set to the REST API of the same installation.

Then use the audience of the installation instead of `currents:record-key`:

* GitHub Actions: set `CURRENTS_OIDC_AUDIENCE` in the job. The `oidcAudience` reporter option of `@currents/playwright` and the `--oidc-audience` option of the `currents` CLI do the same, and take priority over the variable. For `cancel-run-gh-action`, also set `director-url` to the director of the installation.

  ```yaml
  env:
    CURRENTS_OIDC_AUDIENCE: currents:record-key:acme
  ```
* GitLab, CircleCI, Buildkite and Bitbucket Pipelines: use the audience of the installation where the examples use `currents:record-key`. For example, in GitLab:

  ```yaml
  id_tokens:
    CURRENTS_OIDC_TOKEN:
      aud: currents:record-key:acme
  ```

### Self-managed GitLab and GitHub Enterprise Server

The operator lists the instances in `OIDC_EXTRA_ISSUERS`, as comma-separated `provider=issuer` entries:

```
OIDC_EXTRA_ISSUERS=gitlab=https://gitlab.acme.internal,github=https://ghes.acme.internal/_services/token
```

* The provider is `gitlab` or `github`. A self-managed GitLab uses the URL of the instance as its issuer. GitHub Enterprise Server uses `https://HOSTNAME/_services/token`.
* Currents compares the issuer with the `iss` claim of the token as an exact string. The issuer must be `https`, with a lowercase host, no default port, and no user, password, trailing slash, query or fragment. The director and the API refuse to start with an issuer of a cloud provider, an issuer listed twice, or more than 20 entries.
* The director fetches the signing keys of each listed instance over https and does not follow redirects. For an instance with a certificate from your own certificate authority, set `NODE_EXTRA_CA_CERTS` on the director to the path of a PEM file in the container.
* A trust policy for an instance matches only tokens from that instance, even when its IDs equal IDs on GitLab.com or github.com. To create one, pick the instance in the **Server** menu of **Create trust policy**, and enter the IDs.

**Self-managed GitLab.** Use the same `id_tokens` entry as for GitLab.com, with the audience of the installation:

```yaml
playwright:
  image: mcr.microsoft.com/playwright:YOUR_PLAYWRIGHT_VERSION
  id_tokens:
    CURRENTS_OIDC_TOKEN:
      aud: currents:record-key:acme
  script:
    - npm ci
    - npx pwc --project-id YOUR_PROJECT_ID
```

**GitHub Enterprise Server.** Use the same workflow as for GitHub Actions, with `CURRENTS_API_URL` and `CURRENTS_OIDC_AUDIENCE` set for the installation:

```yaml
permissions:
  id-token: write
  contents: read
jobs:
  test:
    runs-on: [self-hosted]
    env:
      CURRENTS_PROJECT_ID: ${{ vars.CURRENTS_PROJECT_ID }}
      CURRENTS_API_URL: https://currents.acme.internal
      CURRENTS_OIDC_AUDIENCE: currents:record-key:acme
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx pwc
```

The runner must trust the certificates of the Currents installation and of the instance when they come from an internal certificate authority.

## Next step

{% content-ref url="/pages/sH02jqxKMiXN9BCHUaQn" %}
[Record Key](/guides/record-key.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.currents.dev/guides/record-key/record-from-ci-with-oidc.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
