From 41fd53ea00b15983e98749f235d86cd6a8f51959 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Fri, 24 Jul 2026 17:31:21 -0700 Subject: [PATCH 01/17] docs: add currents cancel A cancelled CI job stops reporting mid-run, so the run stays in progress until the project's inactivity timeout. `currents cancel` cancels it using the record key the job already holds, on any CI provider. - new page under @currents/cmd, listed in the subcommands and in SUMMARY - a "Cancelling Runs from CI" section on the cancel-run page, above the API and GitHub Action sections - a note on the GitHub Action section, since that route needs an API key --- SUMMARY.md | 1 + dashboard/runs/cancel-run.md | 16 +++++ resources/reporters/currents-cmd/README.md | 1 + .../reporters/currents-cmd/currents-cancel.md | 62 +++++++++++++++++++ 4 files changed, 80 insertions(+) create mode 100644 resources/reporters/currents-cmd/currents-cancel.md diff --git a/SUMMARY.md b/SUMMARY.md index 47c5e78e..252f9d58 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -169,6 +169,7 @@ - [currents api](resources/reporters/currents-cmd/currents-api.md) - [currents upload](resources/reporters/currents-cmd/currents-upload.md) - [currents cache](resources/reporters/currents-cmd/currents-cache.md) + - [currents cancel](resources/reporters/currents-cmd/currents-cancel.md) - [currents convert](resources/reporters/currents-cmd/currents-convert.md) - [Changelog](https://github.com/currents-dev/currents-reporter/blob/main/packages/cmd/CHANGELOG.md) - [@currents/jest](resources/reporters/currents-jest/README.md) diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md index d103b547..8223a363 100644 --- a/dashboard/runs/cancel-run.md +++ b/dashboard/runs/cancel-run.md @@ -26,6 +26,18 @@ The canceled run will be tagged accordingly, and the dashboard will display the

Example of a run cancelled by a dashboard user

+## Cancelling Runs from CI + +When a CI job is cancelled — manually, or because a newer commit superseded it — it stops reporting mid-run, and the run stays in progress until it hits the project's [run-timeouts.md](run-timeouts.md "mention"). Add a step that cancels the run when the job is cancelled: + +```yaml +- name: Cancel the run if the workflow is cancelled + if: ${{ cancelled() }} + run: npx currents cancel +``` + +[`currents cancel`](../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../guides/record-key.md "mention") the job already uses to report results, so it needs no additional secret, and it identifies the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") — which makes it work on any CI provider. See [currents-cancel.md](../../resources/reporters/currents-cmd/currents-cancel.md "mention") for the available options. + ## Cancelling Runs via API You can programmatically cancel a run via the `PUT runs/:runId/cancel` HTTP API call. For example, here is an example of `curl` command that cancels a particular run @@ -51,6 +63,10 @@ If you have [fail-fast-strategy.md](../../guides/ci-optimization/fail-fast-strat ## GitHub Actions Workflow Cancellation +{% hint style="info" %} +The action below authenticates with an API key. If you would rather not add a second secret to your workflow, [currents-cancel.md](../../resources/reporters/currents-cmd/currents-cancel.md "mention") does the same using the record key the workflow already has. +{% endhint %} + You can automatically cancel Currents runs (cypress and playwright) when cancelling GitHub Actions workflow using [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action). Check out the [example workflow configuration](https://github.com/currents-dev/currents-examples/blob/main/cypress/github-actions/.github/workflows/currents.yml): diff --git a/resources/reporters/currents-cmd/README.md b/resources/reporters/currents-cmd/README.md index 6702ad3e..fcdb9424 100644 --- a/resources/reporters/currents-cmd/README.md +++ b/resources/reporters/currents-cmd/README.md @@ -28,6 +28,7 @@ npm install @currents/cmd --save-dev * [`currents api`](currents-api.md) - retrieve data from Currents [Resources](https://app.gitbook.com/s/lcxad7NaXT7D2V6owvHN/resources "mention") entities * [`currents upload`](currents-upload.md) - upload the test results into the Currents Dashboard * [`currents cache`](currents-cache.md) - manage test artifacts and configuration cache +* [`currents cancel`](currents-cancel.md) - cancel a run in progress, e.g. when its CI job is cancelled * [`currents convert`](currents-convert.md) - convert test reports to Currents internal format ### Troubleshooting diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md new file mode 100644 index 00000000..e5667170 --- /dev/null +++ b/resources/reporters/currents-cmd/currents-cancel.md @@ -0,0 +1,62 @@ +--- +description: Learn how to cancel a run from CI using the currents cancel CLI command +--- + +# currents cancel + +`currents cancel` cancels a run that is still in progress, for example when the CI job that recorded it is cancelled. + +A cancelled CI job stops reporting mid-run, so without an explicit cancellation the run stays in progress until it hits the project's [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention"). + +### Usage + +{% hint style="info" %} +The command authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results — no API key is needed. It accepts `--key`, `--project-id` and `--ci-build-id`, or the `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` environment variables. +{% endhint %} + +```bash +npx currents cancel --key --project-id --ci-build-id +``` + +The run is identified by the [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention") it was recorded with, so pass the same value the reporting step used. + +### Cancelling from GitHub Actions + +A job that already exports the record key, project and CI build id needs no arguments: + +```yaml +- name: Run tests + env: + CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }} + CURRENTS_PROJECT_ID: my-project-id + CURRENTS_CI_BUILD_ID: ${{ github.run_id }}-${{ github.run_attempt }} + run: npx playwright test + +- name: Cancel the run if the workflow is cancelled + if: ${{ cancelled() }} + env: + CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }} + CURRENTS_PROJECT_ID: my-project-id + CURRENTS_CI_BUILD_ID: ${{ github.run_id }}-${{ github.run_attempt }} + run: npx currents cancel +``` + +### Cancelling from other CI providers + +The command only needs the record key, the project and the CI build id, so the same step works anywhere. GitLab CI, for example: + +```yaml +cancel_currents_run: + stage: .post + when: on_failure + script: + - npx currents cancel + variables: + CURRENTS_CI_BUILD_ID: $CI_PIPELINE_ID +``` + +### Notes + +* Every job of a parallelized run records into the same run. Cancelling a run that is already cancelled succeeds, so it is safe for each job to run the command. +* A run only exists once results have been recorded. Cancelling before the first results were uploaded reports that no run was found for the CI build id. +* Cancelled runs are marked in the dashboard and trigger the usual integrations. See [cancel-run.md](../../../dashboard/runs/cancel-run.md "mention") for what cancelling a run affects. From 5179ece23fe933bc90e04b448bfbf78293127c69 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Fri, 24 Jul 2026 18:06:33 -0700 Subject: [PATCH 02/17] docs: document run cancellation on GitHub Actions The GitHub Actions section had no landing page and no cancellation article, and the cancellation examples still required an API key plus the GitHub run id and attempt. - new "Cancel Runs on Workflow Cancellation" article: the `if: cancelled()` step, both credentials, and how it pairs with `cancel-in-progress: true` - the GitHub Actions README now lists what is in the section - the action examples in cancel-run.md use the record key the job already has, with the API key kept as a second option --- SUMMARY.md | 1 + dashboard/runs/cancel-run.md | 60 +++++++-------- .../ci-setup/github-actions/README.md | 25 ++++++ .../ci-setup/github-actions/cancel-runs.md | 76 +++++++++++++++++++ .../reporters/currents-cmd/currents-cancel.md | 2 +- 5 files changed, 130 insertions(+), 34 deletions(-) create mode 100644 getting-started/ci-setup/github-actions/cancel-runs.md diff --git a/SUMMARY.md b/SUMMARY.md index 252f9d58..4e9f03b0 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -11,6 +11,7 @@ - [Sharded runs](getting-started/ci-setup/github-actions/re-run-failed-only-tests-sharded.md) - [Orchestrated runs](getting-started/ci-setup/github-actions/re-run-failed-only-tests-orchestrated-v2.md) - [Custom CI Build ID for Reruns](getting-started/ci-setup/github-actions/custom-ci-build-id-for-reruns.md) + - [Cancel Runs on Workflow Cancellation](getting-started/ci-setup/github-actions/cancel-runs.md) - [Commit data for GitHub Actions](getting-started/ci-setup/github-actions/commit-data-for-github-actions.md) - [Custom Docker runners](getting-started/ci-setup/github-actions/custom-docker-runners.md) - [Named Runners](getting-started/ci-setup/github-actions/named-runners.md) diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md index 8223a363..60418374 100644 --- a/dashboard/runs/cancel-run.md +++ b/dashboard/runs/cancel-run.md @@ -38,6 +38,8 @@ When a CI job is cancelled — manually, or because a newer commit superseded it [`currents cancel`](../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../guides/record-key.md "mention") the job already uses to report results, so it needs no additional secret, and it identifies the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") — which makes it work on any CI provider. See [currents-cancel.md](../../resources/reporters/currents-cmd/currents-cancel.md "mention") for the available options. +On GitHub Actions the same thing is available as an action — see [cancel-runs.md](../../getting-started/ci-setup/github-actions/cancel-runs.md "mention"). + ## Cancelling Runs via API You can programmatically cancel a run via the `PUT runs/:runId/cancel` HTTP API call. For example, here is an example of `curl` command that cancels a particular run @@ -63,31 +65,26 @@ If you have [fail-fast-strategy.md](../../guides/ci-optimization/fail-fast-strat ## GitHub Actions Workflow Cancellation -{% hint style="info" %} -The action below authenticates with an API key. If you would rather not add a second secret to your workflow, [currents-cancel.md](../../resources/reporters/currents-cmd/currents-cancel.md "mention") does the same using the record key the workflow already has. -{% endhint %} - -You can automatically cancel Currents runs (cypress and playwright) when cancelling GitHub Actions workflow using [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action). - -Check out the [example workflow configuration](https://github.com/currents-dev/currents-examples/blob/main/cypress/github-actions/.github/workflows/currents.yml): +On GitHub Actions the same cancellation is also available as an action, [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action). See [cancel-runs.md](../../getting-started/ci-setup/github-actions/cancel-runs.md "mention") for a complete workflow. ```yaml - # Run all Currents tests - - name: Run Cypress on Currents.dev - uses: cypress-io/github-action@v4 - with: - command: npx cypress-cloud run --record --parallel --browser chrome --key ${{ secrets.CURRENTS_RECORD_KEY }} --ci-build-id ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt}} + - name: Run tests + env: + CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }} + CURRENTS_PROJECT_ID: my-project-id + CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} + run: npx playwright test - name: Cancel the run if the workflow is cancelled if: ${{ cancelled() }} uses: currents-dev/cancel-run-gh-action@v1 with: - api-token: ${{ secrets.CURRENTS_API_KEY }} - github-run-id: ${{ github.run_id }} - github-run-attempt: ${{ github.run_attempt }} + record-key: ${{ secrets.CURRENTS_RECORD_KEY }} + project-id: my-project-id + ci-build-id: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} ``` -The example above uses a [GitHub Actions repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `CURRENTS_API_KEY.` For creating a new API secret please refer to [Authentication](https://app.gitbook.com/s/lcxad7NaXT7D2V6owvHN/get-started/authentication "mention"). +All three inputs default to `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID`, so a job that already exports them for the reporting step can use the action with no inputs at all. After the step is enabled, cancelling a GitHub Actions workflow will trigger cancellation: @@ -97,39 +94,36 @@ The associated Currents run will be cancelled with the corresponding notes:
-#### Cancelling with CI Build ID +#### Cancelling with an API key -The current implementation allows to cancel a run with CI information that is usually available in the Github environment variables. +The action also accepts an [api-keys.md](../administration/api-keys.md "mention") instead of a record key. It then identifies the run by the GitHub run id and attempt recorded on it, so no other input is needed: -But sometimes is required to explicitly define what run needs to be cancelled, so this functionality allows cancelling a run with a known CI Build ID (see [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention")) and a project ID (see [projects](../projects/ "mention")) which are usually known beforehand in a CI environment as these are required parameters for executing a run. +```yaml + - name: Cancel the run if the workflow is cancelled + if: ${{ cancelled() }} + uses: currents-dev/cancel-run-gh-action@v1 + with: + api-token: ${{ secrets.CURRENTS_API_KEY }} +``` + +Pass `project-id` and `ci-build-id` as well to identify the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") instead — which is what you need when the workflow records under a CI build ID of its own: ```yaml - # Run all Currents tests - - name: Run Cypress on Currents.dev - uses: cypress-io/github-action@v4 + - name: Run tests env: CURRENTS_CI_BUILD_ID: "a-custom-ci-build-id" CURRENTS_PROJECT_ID: "my-project-id" - with: - command: npx pwc --key ${{ secrets.CURRENTS_RECORD_KEY }} --project-id ${{ CURRENTS_PROJECT_ID }} --ci-build-id ${{ CURRENTS_CI_BUILD_ID }} + run: npx pwc --key ${{ secrets.CURRENTS_RECORD_KEY }} - name: Cancel the run if the workflow is cancelled if: ${{ cancelled() }} uses: currents-dev/cancel-run-gh-action@v1 with: api-token: ${{ secrets.CURRENTS_API_KEY }} - github-run-id: ${{ github.run_id }} - github-run-attempt: ${{ github.run_attempt }} - ci-build-id: ${{ env.CURRENTS_CI_BUILD_ID }} project-id: ${{ env.CURRENTS_PROJECT_ID }} + ci-build-id: ${{ env.CURRENTS_CI_BUILD_ID }} ``` -The example above uses `CURRENTS_CI_BUILD_ID` and `CURRENTS_PROJECT_ID` as beforehand known variables to pass it down to the run cancellation workflow. - -{% hint style="info" %} -`api-token`, `github-run-id` and `github-run-attempt` are still required parameters that must be passed to the cancellation workflow. -{% endhint %} - ## FAQ ### What happens when a run is cancelled? diff --git a/getting-started/ci-setup/github-actions/README.md b/getting-started/ci-setup/github-actions/README.md index 7a5835b5..11f3d19b 100644 --- a/getting-started/ci-setup/github-actions/README.md +++ b/getting-started/ci-setup/github-actions/README.md @@ -1,2 +1,27 @@ +--- +description: Running tests with Currents in GitHub Actions +--- + # GitHub Actions +Start with [playwright-github-actions.md](playwright-github-actions.md "mention") for a workflow that records to Currents, then add what your setup needs from the articles below. + +## Setup + +* [playwright-github-actions.md](playwright-github-actions.md "mention") — a workflow that records tests to Currents, and how to parallelize it. +* [commit-data-for-github-actions.md](commit-data-for-github-actions.md "mention") — get the correct commit, branch and pull request on a run. +* [custom-docker-runners.md](custom-docker-runners.md "mention") — the environment variables to pass when the job runs in your own container. +* [named-runners.md](named-runners.md "mention") — show which runner executed each spec file. + +## Reruns + +* [re-run-failed-only-tests.md](re-run-failed-only-tests.md "mention") — re-run only the tests that failed, for [sharded](re-run-failed-only-tests-sharded.md) and [orchestrated](re-run-failed-only-tests-orchestrated-v2.md) runs. +* [custom-ci-build-id-for-reruns.md](custom-ci-build-id-for-reruns.md "mention") — when your workflow sets its own CI build ID. + +## Cancellation + +* [cancel-runs.md](cancel-runs.md "mention") — cancel the Currents run when the workflow is cancelled, so it does not sit in progress until the run timeout. + +## Examples + +The [currents-examples](https://github.com/currents-dev/currents-examples/tree/main/playwright/ci/github-actions) repository has complete workflows for sharding, orchestration, reruns and visual testing. diff --git a/getting-started/ci-setup/github-actions/cancel-runs.md b/getting-started/ci-setup/github-actions/cancel-runs.md new file mode 100644 index 00000000..671aeec2 --- /dev/null +++ b/getting-started/ci-setup/github-actions/cancel-runs.md @@ -0,0 +1,76 @@ +--- +description: Cancel the Currents run when a GitHub Actions workflow is cancelled +--- + +# Cancel Runs on Workflow Cancellation + +A cancelled workflow stops reporting mid-run. Currents has no way to tell that apart from a job that is still working, so the run stays in progress until it hits the project's [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") — up to an hour of a run sitting in the feed as if it were live. + +Add a step that cancels the run when the job is cancelled: + +```yaml +- name: Cancel the Currents run + if: ${{ cancelled() }} + run: npx currents cancel +``` + +`if: cancelled()` runs the step only when the workflow was cancelled, so it costs nothing on a normal run. + +## Which credential to use + +[`currents cancel`](../../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results, so no additional secret is needed. It identifies the run by its [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention"), which means the same step works on any CI provider. + +The [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action) does the same as a GitHub action and accepts either a record key or an [api-keys.md](../../../dashboard/administration/api-keys.md "mention"): + +```yaml +- name: Cancel the Currents run + if: ${{ cancelled() }} + uses: currents-dev/cancel-run-gh-action@v1 +``` + +With no inputs it reads `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` from the environment the reporting step already sets. See [cancel-run.md](../../../dashboard/runs/cancel-run.md "mention") for the full list of inputs. + +## Full example + +```yaml +name: Run Playwright Tests +on: + pull_request: + branches: [main] + +# Cancel the previous run when a new commit is pushed to the same branch. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + run-tests: + runs-on: ubuntu-latest + env: + CURRENTS_PROJECT_ID: ${{ vars.CURRENTS_PROJECT_ID }} + CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }} + CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "24.x" + - run: npm ci + + - name: Playwright Tests + run: npx playwright test + + - name: Cancel the Currents run + if: ${{ cancelled() }} + run: npx currents cancel +``` + +`concurrency` with `cancel-in-progress: true` is what makes this worth setting up: every push to a branch cancels the workflow still running for the previous commit, and each of those leaves a run behind. + +## Notes + +* **Parallel jobs.** Every job of a parallelized run records into the same run, and every one of them can run the cancellation step. Cancelling a run that is already cancelled succeeds. +* **Nothing recorded yet.** A workflow cancelled before the first results reached Currents has no run to cancel. The step reports that and succeeds, so it does not add a failed step to an already cancelled workflow. +* **Hard cancellations.** A job killed without running its remaining steps — a cancelled job that does not honour `if: cancelled()`, or a runner that disappears — never reaches the step. Those runs still end at the inactivity timeout. + +See [cancel-run.md](../../../dashboard/runs/cancel-run.md "mention") for what cancelling a run affects: test statuses, plan usage, analytics and integrations. diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md index e5667170..351f5e8b 100644 --- a/resources/reporters/currents-cmd/currents-cancel.md +++ b/resources/reporters/currents-cmd/currents-cancel.md @@ -58,5 +58,5 @@ cancel_currents_run: ### Notes * Every job of a parallelized run records into the same run. Cancelling a run that is already cancelled succeeds, so it is safe for each job to run the command. -* A run only exists once results have been recorded. Cancelling before the first results were uploaded reports that no run was found for the CI build id. +* A run only exists once results have been recorded. Cancelling before the first results were uploaded reports that there is no run to cancel and exits successfully, so the step does not fail on an already cancelled job. * Cancelled runs are marked in the dashboard and trigger the usual integrations. See [cancel-run.md](../../../dashboard/runs/cancel-run.md "mention") for what cancelling a run affects. From ead8c7dc0ee84b4eb3d2d61e2f4fd23fe3b6632f Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sat, 25 Jul 2026 21:17:22 -0700 Subject: [PATCH 03/17] docs: cancel a run by its run id `currents cancel` now accepts --run-id / CURRENTS_RUN_ID as well as the CI build id. Also state what happens when a job does not set CURRENTS_CI_BUILD_ID: the generated CI build id includes the test framework, so a cancelling step that rebuilds the value from environment variables does not find the run. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01QYks4ynK7rmCmDuVTVuo1b --- .../ci-setup/github-actions/cancel-runs.md | 4 ++++ .../reporters/currents-cmd/currents-cancel.md | 20 +++++++++++++++++-- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/getting-started/ci-setup/github-actions/cancel-runs.md b/getting-started/ci-setup/github-actions/cancel-runs.md index 671aeec2..bad9d3d7 100644 --- a/getting-started/ci-setup/github-actions/cancel-runs.md +++ b/getting-started/ci-setup/github-actions/cancel-runs.md @@ -20,6 +20,10 @@ Add a step that cancels the run when the job is cancelled: [`currents cancel`](../../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results, so no additional secret is needed. It identifies the run by its [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention"), which means the same step works on any CI provider. +{% hint style="warning" %} +Set `CURRENTS_CI_BUILD_ID` on the job, as the example below does. Without it Currents generates a CI build id that includes the test framework, and the cancelling step cannot reconstruct that value from the environment — it would report that there is no run to cancel. +{% endhint %} + The [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action) does the same as a GitHub action and accepts either a record key or an [api-keys.md](../../../dashboard/administration/api-keys.md "mention"): ```yaml diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md index 351f5e8b..bbeac297 100644 --- a/resources/reporters/currents-cmd/currents-cancel.md +++ b/resources/reporters/currents-cmd/currents-cancel.md @@ -11,14 +11,30 @@ A cancelled CI job stops reporting mid-run, so without an explicit cancellation ### Usage {% hint style="info" %} -The command authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results — no API key is needed. It accepts `--key`, `--project-id` and `--ci-build-id`, or the `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` environment variables. +The command authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results — no API key is needed. It accepts `--key`, `--project-id`, `--ci-build-id` and `--run-id`, or the `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`, `CURRENTS_CI_BUILD_ID` and `CURRENTS_RUN_ID` environment variables. {% endhint %} ```bash npx currents cancel --key --project-id --ci-build-id ``` -The run is identified by the [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention") it was recorded with, so pass the same value the reporting step used. +### Identifying the run + +Pass either the [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention") the run was recorded with, or the run id: + +```bash +npx currents cancel --key --project-id --run-id +``` + +`--run-id` takes precedence when both are set. + +Use `--ci-build-id` for cancelling from CI. Set `CURRENTS_CI_BUILD_ID` on the job — for example `${{ github.run_id }}-${{ github.run_attempt }}` — and both the reporting step and the cancelling step read the same variable, so no value has to be passed between them. + +Use `--run-id` when you already have the run id: it is the last segment of the run URL, `https://app.currents.dev/run/`. This is the option for cancelling a specific run from a script or by hand. + +{% hint style="warning" %} +If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates a CI build id from the CI environment, and the generated value includes the test framework — for example `pw:owner/repo-16873-1`. A cancelling step that rebuilds the CI build id from environment variables will not produce that string and will report that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` explicitly on any job you want to cancel from CI. +{% endhint %} ### Cancelling from GitHub Actions From 23050be87e45b7a04d36c29c06b4897abe7156ca Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sat, 25 Jul 2026 23:43:48 -0700 Subject: [PATCH 04/17] docs: the cancel action also accepts a run id Points the input list at the action's README, which is where it is maintained, rather than at this page. Co-Authored-By: Claude Opus 5 --- dashboard/runs/cancel-run.md | 2 ++ getting-started/ci-setup/github-actions/cancel-runs.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md index 60418374..ae8f67e4 100644 --- a/dashboard/runs/cancel-run.md +++ b/dashboard/runs/cancel-run.md @@ -86,6 +86,8 @@ On GitHub Actions the same cancellation is also available as an action, [cancel- All three inputs default to `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID`, so a job that already exports them for the reporting step can use the action with no inputs at all. +Pass `run-id` instead of `ci-build-id` to cancel a run you already have the id of. It defaults to `CURRENTS_RUN_ID` and takes precedence when both are set. + After the step is enabled, cancelling a GitHub Actions workflow will trigger cancellation:

Example of a cancellation step

diff --git a/getting-started/ci-setup/github-actions/cancel-runs.md b/getting-started/ci-setup/github-actions/cancel-runs.md index bad9d3d7..92dafcff 100644 --- a/getting-started/ci-setup/github-actions/cancel-runs.md +++ b/getting-started/ci-setup/github-actions/cancel-runs.md @@ -32,7 +32,7 @@ The [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action) uses: currents-dev/cancel-run-gh-action@v1 ``` -With no inputs it reads `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` from the environment the reporting step already sets. See [cancel-run.md](../../../dashboard/runs/cancel-run.md "mention") for the full list of inputs. +With no inputs it reads `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` from the environment the reporting step already sets. Like the command, it can also identify the run by its run id — the `run-id` input, or `CURRENTS_RUN_ID`. See the [action's README](https://github.com/currents-dev/cancel-run-gh-action#inputs) for every input. ## Full example From 500723f967fe92f0f08510202f88bc6fd10b6957 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sun, 26 Jul 2026 00:05:28 -0700 Subject: [PATCH 05/17] docs: use the repo-prefixed CI build id in the cancel examples ci-build-id.md recommends `${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }}`, and the other cancellation pages already use it. Also moves the GitLab CI build id to the pipeline level, where the reporting job reads the same value. Co-Authored-By: Claude Opus 5 --- .../reporters/currents-cmd/currents-cancel.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md index bbeac297..cb465345 100644 --- a/resources/reporters/currents-cmd/currents-cancel.md +++ b/resources/reporters/currents-cmd/currents-cancel.md @@ -28,7 +28,7 @@ npx currents cancel --key --project-id --run-id `. This is the option for cancelling a specific run from a script or by hand. @@ -45,7 +45,7 @@ A job that already exports the record key, project and CI build id needs no argu env: CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }} CURRENTS_PROJECT_ID: my-project-id - CURRENTS_CI_BUILD_ID: ${{ github.run_id }}-${{ github.run_attempt }} + CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} run: npx playwright test - name: Cancel the run if the workflow is cancelled @@ -53,24 +53,27 @@ A job that already exports the record key, project and CI build id needs no argu env: CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }} CURRENTS_PROJECT_ID: my-project-id - CURRENTS_CI_BUILD_ID: ${{ github.run_id }}-${{ github.run_attempt }} + CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} run: npx currents cancel ``` ### Cancelling from other CI providers -The command only needs the record key, the project and the CI build id, so the same step works anywhere. GitLab CI, for example: +The command only needs the record key, the project and the CI build id, so the same step works anywhere. Set the CI build id for the whole pipeline, so the job that reports and the job that cancels use the same value. GitLab CI, for example: ```yaml +variables: + CURRENTS_CI_BUILD_ID: $CI_PIPELINE_ID + cancel_currents_run: stage: .post when: on_failure script: - npx currents cancel - variables: - CURRENTS_CI_BUILD_ID: $CI_PIPELINE_ID ``` +`CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses. + ### Notes * Every job of a parallelized run records into the same run. Cancelling a run that is already cancelled succeeds, so it is safe for each job to run the command. From 9f2259bb4cbf87bcf6b4577265a6b960d5a5fdbd Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Sun, 26 Jul 2026 00:06:37 -0700 Subject: [PATCH 06/17] docs: name the run ID alongside the CI build ID Both the command and the action accept either identifier; the intros only mentioned the CI build ID. Co-Authored-By: Claude Opus 5 --- dashboard/runs/cancel-run.md | 2 +- getting-started/ci-setup/github-actions/cancel-runs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md index ae8f67e4..a0e31c8a 100644 --- a/dashboard/runs/cancel-run.md +++ b/dashboard/runs/cancel-run.md @@ -36,7 +36,7 @@ When a CI job is cancelled — manually, or because a newer commit superseded it run: npx currents cancel ``` -[`currents cancel`](../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../guides/record-key.md "mention") the job already uses to report results, so it needs no additional secret, and it identifies the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") — which makes it work on any CI provider. See [currents-cancel.md](../../resources/reporters/currents-cmd/currents-cancel.md "mention") for the available options. +[`currents cancel`](../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../guides/record-key.md "mention") the job already uses to report results, so it needs no additional secret, and it identifies the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") or its run ID — which makes it work on any CI provider. See [currents-cancel.md](../../resources/reporters/currents-cmd/currents-cancel.md "mention") for the available options. On GitHub Actions the same thing is available as an action — see [cancel-runs.md](../../getting-started/ci-setup/github-actions/cancel-runs.md "mention"). diff --git a/getting-started/ci-setup/github-actions/cancel-runs.md b/getting-started/ci-setup/github-actions/cancel-runs.md index 92dafcff..28d13abe 100644 --- a/getting-started/ci-setup/github-actions/cancel-runs.md +++ b/getting-started/ci-setup/github-actions/cancel-runs.md @@ -18,7 +18,7 @@ Add a step that cancels the run when the job is cancelled: ## Which credential to use -[`currents cancel`](../../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results, so no additional secret is needed. It identifies the run by its [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention"), which means the same step works on any CI provider. +[`currents cancel`](../../../resources/reporters/currents-cmd/currents-cancel.md) authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results, so no additional secret is needed. It identifies the run by its [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention") or its run ID, which means the same step works on any CI provider. {% hint style="warning" %} Set `CURRENTS_CI_BUILD_ID` on the job, as the example below does. Without it Currents generates a CI build id that includes the test framework, and the cancelling step cannot reconstruct that value from the environment — it would report that there is no run to cancel. From bc72efe5a8a70c9b98caf69c8ea6dcd1fdc97a7c Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Thu, 30 Jul 2026 14:54:34 -0700 Subject: [PATCH 07/17] docs: name the version currents cancel ships in @currents/cmd 1.10.0 is the first release with the command. npx resolves the latest version, so this only matters for a pinned one. --- resources/reporters/currents-cmd/currents-cancel.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md index cb465345..c62d1a09 100644 --- a/resources/reporters/currents-cmd/currents-cancel.md +++ b/resources/reporters/currents-cmd/currents-cancel.md @@ -8,6 +8,8 @@ description: Learn how to cancel a run from CI using the currents cancel CLI com A cancelled CI job stops reporting mid-run, so without an explicit cancellation the run stays in progress until it hits the project's [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention"). +The command is available from `@currents/cmd` 1.10.0. `npx currents` resolves the latest version, so no change is needed unless the version is pinned. + ### Usage {% hint style="info" %} From 5873f5ed876e3d1db6ab7e53e69b187b8f28f817 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Thu, 30 Jul 2026 15:20:09 -0700 Subject: [PATCH 08/17] docs: keep the API key section at the same level as its siblings The heading skipped from the H2 it sits under straight to H4, the only place in the page that does. --- dashboard/runs/cancel-run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md index a0e31c8a..815c3bea 100644 --- a/dashboard/runs/cancel-run.md +++ b/dashboard/runs/cancel-run.md @@ -96,7 +96,7 @@ The associated Currents run will be cancelled with the corresponding notes:
-#### Cancelling with an API key +### Cancelling with an API key The action also accepts an [api-keys.md](../administration/api-keys.md "mention") instead of a record key. It then identifies the run by the GitHub run id and attempt recorded on it, so no other input is needed: From 45ed475bfd8b8b40425e8ecba6bee8c5f3502dd5 Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Thu, 6 Aug 2026 15:36:36 -0700 Subject: [PATCH 09/17] Fix broken redirects and dead external links Redirect map (.gitbook.yaml): - Repair 23 entries whose target files no longer exist after content moves (ci-setup pages flattened, cypress CI guides moved under other-frameworks/cypress, guides moved to ci-optimization, run-status moved to dashboard/analytics, slack/currents-playwright became directories, resources/api moved to the API space) - Add 14 entries for old URLs that currently hard-404 and are still linked from currents.dev and external sites (billing-and-pricing, administration/billing-and-usage, team-management, old guides/ and ci-setup/ paths, getting-started/playwright) Dead external links (every replacement verified to return 200): - @currents/playwright changelog: the currents-playwright repo is gone; the changelog now lives in currents-dev/currents-playwright-changelog - circleci.com/docs/2.0/* dropped the 2.0 prefix - Harness retired the set-up-cicd-pipelines category page - Slack replaced the Get-user-and-group-IDs article with Locate-your-Slack-URL-or-ID - Applitools moved tutorials/guides/* to docs/eyes/concepts/* (the step-3-closing-the-batch anchor exists at the new URL) - run-details.md linked the reporter configuration page via a raw github.com/currents-dev/currents-readme URL pointing at a path that no longer exists; use a relative mention link instead Co-Authored-By: Claude Fable 5 --- .gitbook.yaml | 60 ++++++++++++------- SUMMARY.md | 2 +- dashboard/runs/run-details.md | 2 +- .../ci-setup/playwright-circleci.md | 4 +- .../ci-setup/playwright-harness.md | 2 +- .../cypress/ci-setup/cypress-circleci.md | 2 +- guides/playwright-visual-testing.md | 2 +- resources/changelog.md | 2 +- resources/integrations/slack/slack-app.md | 2 +- 9 files changed, 46 insertions(+), 32 deletions(-) diff --git a/.gitbook.yaml b/.gitbook.yaml index 341ef0da..b2f3f822 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -1,50 +1,50 @@ root: ./ redirects: - api/api-keys: resources/api/api-keys.md + api/api-keys: dashboard/administration/api-keys.md ci-setup: getting-started/ci-setup/github-actions/README.md ci-setup/gitlab/playwright-gitlab-ci-cd: getting-started/ci-setup/gitlab/playwright-gitlab-ci-cd.md - ci-setup/azure-devops/playwright-azure-devops: getting-started/ci-setup/azure-devops/playwright-azure-devops.md - ci-setup/aws-code-build/playwright-aws-code-build: getting-started/ci-setup/aws-code-build/playwright-aws-code-build.md - ci-setup/circleci/playwright-circleci: getting-started/ci-setup/circleci/playwright-circleci.md + ci-setup/azure-devops/playwright-azure-devops: getting-started/ci-setup/playwright-azure-devops.md + ci-setup/aws-code-build/playwright-aws-code-build: getting-started/ci-setup/playwright-aws-code-build.md + ci-setup/circleci/playwright-circleci: getting-started/ci-setup/playwright-circleci.md ci-setup/github-actions/playwright-github-actions: getting-started/ci-setup/github-actions/playwright-github-actions.md - ci-setup/gitlab/cypress-gitlab-ci-cd: getting-started/ci-setup/gitlab/cypress-gitlab-ci-cd.md - ci-setup/bitbucket/cypress-bitbucket-pipelines: getting-started/ci-setup/bitbucket/cypress-bitbucket-pipelines.md - ci-setup/jenkins/jenkins-playwright: getting-started/ci-setup/jenkins/jenkins-playwright.md - ci-setup/aws-code-build/cypress-aws-code-build: getting-started/ci-setup/aws-code-build/cypress-aws-code-build.md + ci-setup/gitlab/cypress-gitlab-ci-cd: getting-started/other-frameworks/cypress/ci-setup/cypress-gitlab-ci-cd.md + ci-setup/bitbucket/cypress-bitbucket-pipelines: getting-started/other-frameworks/cypress/ci-setup/cypress-bitbucket-pipelines.md + ci-setup/jenkins/jenkins-playwright: getting-started/ci-setup/jenkins.md + ci-setup/aws-code-build/cypress-aws-code-build: getting-started/other-frameworks/cypress/ci-setup/cypress-aws-code-build.md ci-setup/nx: getting-started/ci-setup/nx.md ci-setup/github-actions/commit-data-for-github-actions: getting-started/ci-setup/github-actions/commit-data-for-github-actions.md - ci-setup/circleci/cypress-circleci: getting-started/ci-setup/circleci/cypress-circleci.md - ci-setup/jenkins/cypress-jenkins: getting-started/ci-setup/jenkins/cypress-jenkins.md - ci-setup/azure-devops/cypress-azure-devops: getting-started/ci-setup/azure-devops/cypress-azure-devops.md + ci-setup/circleci/cypress-circleci: getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md + ci-setup/jenkins/cypress-jenkins: getting-started/other-frameworks/cypress/ci-setup/cypress-jenkins.md + ci-setup/azure-devops/cypress-azure-devops: getting-started/other-frameworks/cypress/ci-setup/cypress-azure-devops.md administration/email-domain-based-access: dashboard/administration/email-domain-based-access.md - getting-started/you-first-cypress-run: getting-started/cypress/you-first-cypress-run.md - guides/parallelization: guides/parallelization-guide/cypress-parallelization.md - guides/pw-parallelization/playwright-orchestration: guides/parallelization-guide/pw-parallelization/playwright-orchestration.md + getting-started/you-first-cypress-run: getting-started/other-frameworks/cypress/you-first-cypress-run.md + guides/parallelization: guides/parallelization-guide/README.md + guides/pw-parallelization/playwright-orchestration: guides/ci-optimization/playwright-orchestration.md guides/ci-optimization/playwright-orchestration-v2: guides/ci-optimization/playwright-orchestration-v1.md - guides/pw-parallelization/playwright-sharding: guides/parallelization-guide/pw-parallelization/playwright-sharding.md - guides/load-balancing: guides/parallelization-guide/load-balancing.md - guides/fail-fast-strategy: guides/parallelization-guide/fail-fast-strategy.md + guides/pw-parallelization/playwright-sharding: guides/parallelization-guide/playwright-sharding.md + guides/load-balancing: guides/ci-optimization/load-balancing.md + guides/fail-fast-strategy: guides/ci-optimization/fail-fast-strategy.md insights/runs-analytics: dashboard/analytics/README.md tests/test-status: dashboard/tests/test-status.md tests/flaky-tests: dashboard/tests/flaky-tests.md - tests/spec-file-status: dashboard/tests/spec-file-status.md + tests/spec-file-status: dashboard/spec-file-status/README.md tests/test-history: dashboard/tests/test-history.md runs/run-timeouts: dashboard/runs/run-timeouts.md runs/run-details: dashboard/runs/run-details.md - runs/run-status: dashboard/runs/run-status.md + runs/run-status: dashboard/analytics/run-status.md runs/cancel-run: dashboard/runs/cancel-run.md runs/deleting-runs: dashboard/runs/deleting-runs.md resources/reporters/currents-playwright/pwc-p-orchestration: resources/reporters/currents-playwright/pwc-p.md - integration-with-playwright/currents-playwright: resources/reporters/currents-playwright.md - integration-with-playwright/playwright-component-testing: getting-started/playwright/integration-with-playwright/playwright-component-testing.md - integration-with-playwright/troubleshooting: getting-started/playwright/troubleshooting-playwright.md + integration-with-playwright/currents-playwright: resources/reporters/currents-playwright/README.md + integration-with-playwright/playwright-component-testing: guides/playwright-component-testing.md + integration-with-playwright/troubleshooting: guides/troubleshooting-playwright.md insights/insights-and-analytics: dashboard/analytics/README.md dashboard/insights-and-analytics: dashboard/analytics/README.md integrations/github/github-app: resources/integrations/github/github-app.md integrations/github/github-oauth: resources/integrations/github/github-oauth.md integrations/github: resources/integrations/github/README.md - integrations/slack: resources/integrations/slack.md + integrations/slack: resources/integrations/slack/README.md integrations/gitlab: resources/integrations/gitlab.md integrations/microsoft-teams: resources/integrations/microsoft-teams.md integrations/http-webhooks: resources/integrations/http-webhooks.md @@ -54,3 +54,17 @@ redirects: projects/archive-and-unarchive-projects: dashboard/projects/archive-and-unarchive-projects.md dashboard/billing-and-pricing: dashboard/billing/plans-and-pricing.md dashboard/administration/billing-and-usage: dashboard/billing/usage-and-spend-control.md + billing-and-pricing: dashboard/billing/plans-and-pricing.md + administration/billing-and-usage: dashboard/billing/usage-and-spend-control.md + dashboard/administration/team-management: dashboard/administration/manage-team.md + dashboard/runs/run-status: dashboard/analytics/run-status.md + getting-started/playwright: getting-started/your-first-playwright-run.md + guides/pw-parallelization: guides/ci-optimization/playwright-parallelization.md + guides/parallelization-guide/pw-parallelization: guides/ci-optimization/playwright-parallelization.md + guides/pw-parallelization/ci-tests-on-spot-instances: guides/ci-optimization/ci-tests-on-spot-instances.md + guides/playwright-rerun-failed-tests: guides/ci-optimization/re-run-only-failed-tests.md + getting-started/ci-setup/circleci: getting-started/ci-setup/playwright-circleci.md + getting-started/ci-setup/azure-devops: getting-started/ci-setup/playwright-azure-devops.md + getting-started/ci-setup/aws-code-build: getting-started/ci-setup/playwright-aws-code-build.md + getting-started/ci-setup/bitbucket: getting-started/other-frameworks/cypress/ci-setup/cypress-bitbucket-pipelines.md + getting-started/ci-setup/nx/playwright-nx: getting-started/ci-setup/nx.md diff --git a/SUMMARY.md b/SUMMARY.md index c738af3b..e0c1ccdc 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -166,7 +166,7 @@ * [pwc-p discover](resources/reporters/currents-playwright/pwc-p-discover.md) * [pwc-p run](resources/reporters/currents-playwright/pwc-p-run.md) * [Playwright Fixtures](resources/reporters/currents-playwright/playwright-fixtures.md) - * [Changelog](https://github.com/currents-dev/currents-playwright/blob/main/CHANGELOG.md) + * [Changelog](https://github.com/currents-dev/currents-playwright-changelog/blob/main/CHANGELOG.md) * [@currents/cmd](resources/reporters/currents-cmd/README.md) * [currents api](resources/reporters/currents-cmd/currents-api.md) * [currents upload](resources/reporters/currents-cmd/currents-upload.md) diff --git a/dashboard/runs/run-details.md b/dashboard/runs/run-details.md index 3aa0fa5b..327ef362 100644 --- a/dashboard/runs/run-details.md +++ b/dashboard/runs/run-details.md @@ -43,4 +43,4 @@ Currents collects additional information about the CI environment: | Browser / Project | Cypress tests browser or Playwright Project | | Author | Git commit author | | CI Build ID | [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") | -| CI Provider Link | Auto-detected or custom CI job/run URL. Set `CURRENTS_CI_URL` to override. See [https://github.com/currents-dev/currents-readme/blob/main/dashboard/reporters/currents-playwright/configuration.md](https://github.com/currents-dev/currents-readme/blob/main/dashboard/reporters/currents-playwright/configuration.md "mention") | +| CI Provider Link | Auto-detected or custom CI job/run URL. Set `CURRENTS_CI_URL` to override. See [configuration.md](../../resources/reporters/currents-playwright/configuration.md "mention") | diff --git a/getting-started/ci-setup/playwright-circleci.md b/getting-started/ci-setup/playwright-circleci.md index ffa6117f..0aea1d1e 100644 --- a/getting-started/ci-setup/playwright-circleci.md +++ b/getting-started/ci-setup/playwright-circleci.md @@ -10,11 +10,11 @@ TL;DR Check out the example repository: [https://github.com/currents-dev/currents-examples](https://github.com/currents-dev/currents-examples/tree/main/playwright/ci/circleci) {% endhint %} -Run Playwright tests in [parallel on CircleCI](https://circleci.com/docs/2.0/parallelism-faster-jobs/) using the native [Playwright Sharding](https://playwright.dev/docs/test-sharding) to split the tests between multiple containers. Parallelizing the test will help in decreasing the overall run duration. +Run Playwright tests in [parallel on CircleCI](https://circleci.com/docs/parallelism-faster-jobs/) using the native [Playwright Sharding](https://playwright.dev/docs/test-sharding) to split the tests between multiple containers. Parallelizing the test will help in decreasing the overall run duration. Currents collects the results of distributed parallel CircleCI builds for more efficient troubleshooting. Each container will receive a unique set of tests to run so that your tests will run faster and you can receive faster feedback from your browser test suite. -Create multiple containers that will run your tests in parallel by setting the desired amount of containers with [`parallelism`](https://circleci.com/docs/2.0/configuration-reference/#parallelism) flag in `config.yaml` file. +Create multiple containers that will run your tests in parallel by setting the desired amount of containers with [`parallelism`](https://circleci.com/docs/configuration-reference/#parallelism) flag in `config.yaml` file. Please refer to the [example repository](https://github.com/currents-dev/currents-examples/tree/main/playwright/ci/circleci) demonstrating how to set up [CircleCI](https://circleci.com) for running Playwright tests in parallel using [Currents](https://currents.dev) service. diff --git a/getting-started/ci-setup/playwright-harness.md b/getting-started/ci-setup/playwright-harness.md index 170d5594..88c490a9 100644 --- a/getting-started/ci-setup/playwright-harness.md +++ b/getting-started/ci-setup/playwright-harness.md @@ -4,7 +4,7 @@ description: Running Playwright tests on Harness CI with Currents reporting and # Harness -This guide explains how to run Playwright tests on [Harness Continuous Integration](https://developer.harness.io/docs/category/set-up-cicd-pipelines) and report results to [Currents](https://currents.dev). It follows Harness NextGen pipeline patterns ([Run steps](https://developer.harness.io/docs/continuous-integration/use-ci/run-step-settings), [stage parallelism](https://developer.harness.io/docs/continuous-integration/use-ci/run-tests/speed-up-ci-test-pipelines-using-parallelism), [secrets](https://developer.harness.io/docs/platform/secrets/add-use-text-secrets)). +This guide explains how to run Playwright tests on [Harness Continuous Integration](https://developer.harness.io/docs/continuous-integration/) and report results to [Currents](https://currents.dev). It follows Harness NextGen pipeline patterns ([Run steps](https://developer.harness.io/docs/continuous-integration/use-ci/run-step-settings), [stage parallelism](https://developer.harness.io/docs/continuous-integration/use-ci/run-tests/speed-up-ci-test-pipelines-using-parallelism), [secrets](https://developer.harness.io/docs/platform/secrets/add-use-text-secrets)). {% hint style="warning" %} **`CURRENTS_CI_BUILD_ID` is mandatory** for Harness. Harness is **not** in Currents’ [auto-detected CI providers](../../guides/parallelization-guide/ci-build-id.md#build-id-for-popular-ci-providers). If you omit it, Currents may generate a **different** build ID per job or shard: parallel Playwright shards **will not merge into one run**, reporting and orchestration **break**, and **retries** can collide with or duplicate prior runs. Always set `CURRENTS_CI_BUILD_ID` in every Run step (see below). diff --git a/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md b/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md index ba043b04..2f547e7c 100644 --- a/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md +++ b/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md @@ -22,7 +22,7 @@ The example [config file](https://github.com/currents-dev/currents-examples/blob * Obtain **ProjectId** and **Record Key**. * Set `CURRENTS_RECORD_KEY`: * create [CircleCI context](https://circleci.com/docs/contexts/) and set `CURRENTS_RECORD_KEY`. - * alternatively, set [Environment variable](https://circleci.com/docs/2.0/env-vars/) `CURRENTS_RECORD_KEY` + * alternatively, set [Environment variable](https://circleci.com/docs/env-vars/) `CURRENTS_RECORD_KEY` * Follow the setup instructions at [https://currents.dev/readme/integration-with-cypress/cypress-cloud](https://currents.dev/readme/integration-with-cypress/cypress-cloud) to create `currents.config.js` set your `projectId` ### Bare CircleCI configuration diff --git a/guides/playwright-visual-testing.md b/guides/playwright-visual-testing.md index 65717eed..036fcb17 100644 --- a/guides/playwright-visual-testing.md +++ b/guides/playwright-visual-testing.md @@ -222,5 +222,5 @@ function assertEnvVariable(name: string) { You can use the same concept to send a "finalize" command to other visual testing tools like Applitools and Percy. -* Applitools - refer to [Closing the Batch](https://applitools.com/tutorials/guides/advanced-use-cases/parallel-test-suites#step-3-closing-the-batch) section the Parallel Test Suites guide +* Applitools - refer to [Closing the Batch](https://applitools.com/docs/eyes/concepts/test-execution/parallel-test-suites#step-3-closing-the-batch) section the Parallel Test Suites guide * Percy - refer to `percy build:finalize` step in [Percy documentation](https://www.browserstack.com/docs/percy/integrate/parallel-test-suites) diff --git a/resources/changelog.md b/resources/changelog.md index 5246f5de..55d310eb 100644 --- a/resources/changelog.md +++ b/resources/changelog.md @@ -6,7 +6,7 @@ icon: square-rss # Changelog * [Changelog](https://changelog.currents.dev/changelog) - main platform updates and improvements -* [@currents/playwright](https://github.com/currents-dev/currents-playwright/blob/main/CHANGELOG.md) - Playwright reporter for Currents changelog +* [@currents/playwright](https://github.com/currents-dev/currents-playwright-changelog/blob/main/CHANGELOG.md) - Playwright reporter for Currents changelog * [@currents/cmd](https://github.com/currents-dev/currents-reporter/blob/main/packages/cmd/CHANGELOG.md) - CLI utilities and generic XML reporter for Currents changelog * [@currents/jest](https://github.com/currents-dev/currents-reporter/blob/main/packages/jest/CHANGELOG.md) - Jest reporter for Currents changelog * [@currents/node-test-reporter](https://github.com/currents-dev/currents-reporter/blob/main/packages/node-test-reporter/CHANGELOG.md) - NodeJS Test Runner reporter for Currents changelog diff --git a/resources/integrations/slack/slack-app.md b/resources/integrations/slack/slack-app.md index 25c4c9ad..db574ddd 100644 --- a/resources/integrations/slack/slack-app.md +++ b/resources/integrations/slack/slack-app.md @@ -299,7 +299,7 @@ Both [Annotation-Based Mentions](#annotation-based-mentions) and [UI-Based Menti | **Multiple Mentions** | Comma-separated combination of formats | `user:U01RWNBFGER, team:S07JCUP81EG, miguel@currents.dev` | {% hint style="info" %} -**Finding Slack IDs:** See [Slack's documentation](https://slack.com/help/articles/360057541954-Get-user-and-group-IDs) for instructions on finding user and group IDs. +**Finding Slack IDs:** See [Slack's documentation](https://slack.com/help/articles/221769328-Locate-your-Slack-URL-or-ID) for instructions on finding user and group IDs. {% endhint %} ## Disabling Slack Integration From d94f467f3c6c2f527e95f8cbe2887bbf14a31c2e Mon Sep 17 00:00:00 2001 From: Andrew Goldis Date: Fri, 7 Aug 2026 23:34:35 -0700 Subject: [PATCH 10/17] Address review feedback on the cancel docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cancellation examples could not work as written: - dashboard/runs/cancel-run.md declared CURRENTS_PROJECT_ID and CURRENTS_CI_BUILD_ID in the reporting step's env, then read them back as ${{ env.* }} from the cancelling step, where a step's env is not visible. Both examples now declare them on the job. - currents-cancel.md's GitLab example used `when: on_failure`, which fires on a failed job, not a cancelled one — so the one case the page exists to cover was the case it did not handle. Replaced with an after_script that checks CI_JOB_STATUS, which GitLab does run on cancellation, plus a note that force cancel skips after_script. - The CI build id warning described only the framework-prefixed value generated for a recognised CI provider. Unrecognised providers get a random id instead; neither is reproducible by a separate step, which is the point the warning was making. Also: CircleCI links pointed at aliases that 301 to the guides/ and reference/ tree, and cypress-circleci linked setup instructions through currents.dev/readme/*, which redirects twice before landing on resources/reporters/cypress-cloud. Both now point at the final target. The parallelism sentence said "flag in config.yaml"; it is a key, and the file in the example is .circleci/config.yml. Not changed: MD001 wants ## rather than ### after the H1 in currents-cancel.md. All six files in resources/reporters/currents-cmd/ use ### with no H2, so fixing this one alone makes it the odd one out, and fixing all six is unrelated to this PR. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP --- dashboard/runs/cancel-run.md | 26 ++++++---- .../ci-setup/github-actions/cancel-runs.md | 2 +- .../ci-setup/playwright-circleci.md | 6 +-- .../cypress/ci-setup/cypress-circleci.md | 6 +-- .../reporters/currents-cmd/currents-cancel.md | 48 +++++++++++-------- 5 files changed, 52 insertions(+), 36 deletions(-) diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md index 815c3bea..96100c69 100644 --- a/dashboard/runs/cancel-run.md +++ b/dashboard/runs/cancel-run.md @@ -110,20 +110,28 @@ The action also accepts an [api-keys.md](../administration/api-keys.md "mention" Pass `project-id` and `ci-build-id` as well to identify the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") instead — which is what you need when the workflow records under a CI build ID of its own: +Declare the variables on the job, not on the reporting step — a step's `env` +is not visible to any other step, so the cancelling step would read them as +empty: + ```yaml - - name: Run tests +jobs: + run-tests: + runs-on: ubuntu-latest env: CURRENTS_CI_BUILD_ID: "a-custom-ci-build-id" CURRENTS_PROJECT_ID: "my-project-id" - run: npx pwc --key ${{ secrets.CURRENTS_RECORD_KEY }} + steps: + - name: Run tests + run: npx pwc --key ${{ secrets.CURRENTS_RECORD_KEY }} - - name: Cancel the run if the workflow is cancelled - if: ${{ cancelled() }} - uses: currents-dev/cancel-run-gh-action@v1 - with: - api-token: ${{ secrets.CURRENTS_API_KEY }} - project-id: ${{ env.CURRENTS_PROJECT_ID }} - ci-build-id: ${{ env.CURRENTS_CI_BUILD_ID }} + - name: Cancel the run if the workflow is cancelled + if: ${{ cancelled() }} + uses: currents-dev/cancel-run-gh-action@v1 + with: + api-token: ${{ secrets.CURRENTS_API_KEY }} + project-id: ${{ env.CURRENTS_PROJECT_ID }} + ci-build-id: ${{ env.CURRENTS_CI_BUILD_ID }} ``` ## FAQ diff --git a/getting-started/ci-setup/github-actions/cancel-runs.md b/getting-started/ci-setup/github-actions/cancel-runs.md index 28d13abe..1fb6f4c4 100644 --- a/getting-started/ci-setup/github-actions/cancel-runs.md +++ b/getting-started/ci-setup/github-actions/cancel-runs.md @@ -32,7 +32,7 @@ The [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action) uses: currents-dev/cancel-run-gh-action@v1 ``` -With no inputs it reads `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` from the environment the reporting step already sets. Like the command, it can also identify the run by its run id — the `run-id` input, or `CURRENTS_RUN_ID`. See the [action's README](https://github.com/currents-dev/cancel-run-gh-action#inputs) for every input. +With no inputs it reads `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` from the job's environment, the way the full example below declares them. Declaring them on the reporting step instead leaves them empty here, since a step's `env` is visible only to that step. Like the command, it can also identify the run by its run id — the `run-id` input, or `CURRENTS_RUN_ID`. See the [action's README](https://github.com/currents-dev/cancel-run-gh-action#inputs) for every input. ## Full example diff --git a/getting-started/ci-setup/playwright-circleci.md b/getting-started/ci-setup/playwright-circleci.md index 0aea1d1e..3aa66aa6 100644 --- a/getting-started/ci-setup/playwright-circleci.md +++ b/getting-started/ci-setup/playwright-circleci.md @@ -10,18 +10,18 @@ TL;DR Check out the example repository: [https://github.com/currents-dev/currents-examples](https://github.com/currents-dev/currents-examples/tree/main/playwright/ci/circleci) {% endhint %} -Run Playwright tests in [parallel on CircleCI](https://circleci.com/docs/parallelism-faster-jobs/) using the native [Playwright Sharding](https://playwright.dev/docs/test-sharding) to split the tests between multiple containers. Parallelizing the test will help in decreasing the overall run duration. +Run Playwright tests in [parallel on CircleCI](https://circleci.com/docs/guides/optimize/parallelism-faster-jobs/) using the native [Playwright Sharding](https://playwright.dev/docs/test-sharding) to split the tests between multiple containers. Parallelizing the test will help in decreasing the overall run duration. Currents collects the results of distributed parallel CircleCI builds for more efficient troubleshooting. Each container will receive a unique set of tests to run so that your tests will run faster and you can receive faster feedback from your browser test suite. -Create multiple containers that will run your tests in parallel by setting the desired amount of containers with [`parallelism`](https://circleci.com/docs/configuration-reference/#parallelism) flag in `config.yaml` file. +Create multiple containers that will run your tests in parallel by setting the desired amount of containers with the [`parallelism`](https://circleci.com/docs/reference/configuration-reference/#parallelism) key in the `.circleci/config.yml` file. Please refer to the [example repository](https://github.com/currents-dev/currents-examples/tree/main/playwright/ci/circleci) demonstrating how to set up [CircleCI](https://circleci.com) for running Playwright tests in parallel using [Currents](https://currents.dev) service. * Create an organization at https://app.currents.dev * Create a new project * Grab `CURRENTS_RECORD_KEY` [record-key.md](../../guides/record-key.md "mention") and `CURRENTS_PROJECT_ID` -* Store `CURRENTS_RECORD_KEY`: [https://circleci.com/docs/contexts/](https://circleci.com/docs/contexts/) +* Store `CURRENTS_RECORD_KEY`: [https://circleci.com/docs/guides/security/contexts/](https://circleci.com/docs/guides/security/contexts/) 
# .circleci/config.yml
 version: 2.1
diff --git a/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md b/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md
index 2f547e7c..0b40803d 100644
--- a/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md
+++ b/getting-started/other-frameworks/cypress/ci-setup/cypress-circleci.md
@@ -21,9 +21,9 @@ The example [config file](https://github.com/currents-dev/currents-examples/blob
 * Create an account at https:/app.currents.dev.
 * Obtain **ProjectId** and **Record Key**.
 * Set `CURRENTS_RECORD_KEY`:
-  * create [CircleCI context](https://circleci.com/docs/contexts/) and set `CURRENTS_RECORD_KEY`.
-  * alternatively, set [Environment variable](https://circleci.com/docs/env-vars/) `CURRENTS_RECORD_KEY`
-* Follow the setup instructions at [https://currents.dev/readme/integration-with-cypress/cypress-cloud](https://currents.dev/readme/integration-with-cypress/cypress-cloud) to create `currents.config.js` set your `projectId`
+  * create [CircleCI context](https://circleci.com/docs/guides/security/contexts/) and set `CURRENTS_RECORD_KEY`.
+  * alternatively, set [Environment variable](https://circleci.com/docs/guides/security/env-vars/) `CURRENTS_RECORD_KEY`
+* Follow the setup instructions at [cypress-cloud](../../../../resources/reporters/cypress-cloud/README.md "mention") to create `currents.config.js` set your `projectId`
 
 ### Bare CircleCI configuration
 
diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index c62d1a09..259b1ccc 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -35,7 +35,7 @@ Use `--ci-build-id` for cancelling from CI. Set `CURRENTS_CI_BUILD_ID` on the jo
 Use `--run-id` when you already have the run id: it is the last segment of the run URL, `https://app.currents.dev/run/`. This is the option for cancelling a specific run from a script or by hand.
 
 {% hint style="warning" %}
-If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates a CI build id from the CI environment, and the generated value includes the test framework — for example `pw:owner/repo-16873-1`. A cancelling step that rebuilds the CI build id from environment variables will not produce that string and will report that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` explicitly on any job you want to cancel from CI.
+If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and neither of the two forms it can take is reproducible by a separate step. On a CI provider Currents recognises, the value is derived from that provider's environment variables and carries a test framework prefix — for example `pw:owner/repo-16873-1`. On a provider it does not recognise, the value is a random id that never leaves the reporting process. Either way a cancelling step that rebuilds the CI build id from the environment produces a different string and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` explicitly on any job you want to cancel from CI.
 {% endhint %}
 
 ### Cancelling from GitHub Actions
@@ -43,39 +43,47 @@ If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates a CI build id
 A job that already exports the record key, project and CI build id needs no arguments:
 
 ```yaml
-- name: Run tests
-  env:
-    CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }}
-    CURRENTS_PROJECT_ID: my-project-id
-    CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }}
-  run: npx playwright test
-
-- name: Cancel the run if the workflow is cancelled
-  if: ${{ cancelled() }}
-  env:
-    CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }}
-    CURRENTS_PROJECT_ID: my-project-id
-    CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }}
-  run: npx currents cancel
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    env:
+      CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }}
+      CURRENTS_PROJECT_ID: my-project-id
+      CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }}
+    steps:
+      - name: Run tests
+        run: npx playwright test
+
+      - name: Cancel the run if the workflow is cancelled
+        if: ${{ cancelled() }}
+        run: npx currents cancel
 ```
 
+Declaring them on the job rather than on each step is what makes "no arguments" work: a step's `env` is visible only to that step.
+
 ### Cancelling from other CI providers
 
-The command only needs the record key, the project and the CI build id, so the same step works anywhere. Set the CI build id for the whole pipeline, so the job that reports and the job that cancels use the same value. GitLab CI, for example:
+The command only needs the record key, the project and the CI build id, so the same step works anywhere. Set the CI build id for the whole pipeline, so the reporting job and the cancelling step use the same value. GitLab CI, for example:
 
 ```yaml
 variables:
   CURRENTS_CI_BUILD_ID: $CI_PIPELINE_ID
 
-cancel_currents_run:
-  stage: .post
-  when: on_failure
+playwright_tests:
   script:
-    - npx currents cancel
+    - npx playwright test
+  after_script:
+    - if [ "$CI_JOB_STATUS" = "canceled" ]; then npx currents cancel; fi
 ```
 
 `CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses.
 
+GitLab runs `after_script` when a job is cancelled, which is what makes this work; there is no `when:` value that matches cancellation. `when: on_failure` in particular does not fire — it triggers on a failed job, and a cancelled job is not a failed one.
+
+{% hint style="info" %}
+Force cancelling a job skips `after_script`, so those runs still end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
+{% endhint %}
+
 ### Notes
 
 * Every job of a parallelized run records into the same run. Cancelling a run that is already cancelled succeeds, so it is safe for each job to run the command.

From 9e78b50cddfd0376bb387fe133cc087f2c257334 Mon Sep 17 00:00:00 2001
From: Andrew Goldis 
Date: Sat, 8 Aug 2026 00:02:50 -0700
Subject: [PATCH 11/17] Cover GitLab cancellation prerequisites and record key
 handling

Follow-up review on the GitLab example raised three things the page did
not say:

- CURRENTS_CI_BUILD_ID: $CI_PIPELINE_ID is shared across a pipeline's jobs,
  which is what a CI build id needs, but it does not change when a single
  job is retried. That contradicts the guidance in ci-build-id.md to
  include a retry identifier, so the caveat is now stated with the two ways
  out: re-run the pipeline, or append a per-attempt value.
- after_script only runs on cancellation from GitLab 17.0 and Runner 16.10;
  before that the job just stops. Pending and force-cancelled jobs skip it
  on every version. Those runs still end at the inactivity timeout.
- CURRENTS_RECORD_KEY is a credential and the example passed it as an
  ordinary pipeline variable. Now says to mask it, and protect it where the
  branch policy allows.

Also replaced "never leaves the reporting process" in the CI build id
warning: the point is that a separate currents cancel invocation cannot
recover the generated value, which is what the sentence now says.

Co-Authored-By: Claude Opus 5 (1M context) 
Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP
---
 .../reporters/currents-cmd/currents-cancel.md | 20 +++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index 259b1ccc..4948d831 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -4,11 +4,11 @@ description: Learn how to cancel a run from CI using the currents cancel CLI com
 
 # currents cancel
 
-`currents cancel` cancels a run that is still in progress, for example when the CI job that recorded it is cancelled.
+`currents cancel` cancels a run that is still in progress, for example when you stop the associated CI job.
 
 A cancelled CI job stops reporting mid-run, so without an explicit cancellation the run stays in progress until it hits the project's [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention").
 
-The command is available from `@currents/cmd` 1.10.0. `npx currents` resolves the latest version, so no change is needed unless the version is pinned.
+The command is available from `@currents/cmd` 1.10.0.
 
 ### Usage
 
@@ -35,7 +35,7 @@ Use `--ci-build-id` for cancelling from CI. Set `CURRENTS_CI_BUILD_ID` on the jo
 Use `--run-id` when you already have the run id: it is the last segment of the run URL, `https://app.currents.dev/run/`. This is the option for cancelling a specific run from a script or by hand.
 
 {% hint style="warning" %}
-If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and neither of the two forms it can take is reproducible by a separate step. On a CI provider Currents recognises, the value is derived from that provider's environment variables and carries a test framework prefix — for example `pw:owner/repo-16873-1`. On a provider it does not recognise, the value is a random id that never leaves the reporting process. Either way a cancelling step that rebuilds the CI build id from the environment produces a different string and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` explicitly on any job you want to cancel from CI.
+If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and neither of the two forms it can take is reproducible by a separate step. On a CI provider Currents recognises, the value is derived from that provider's environment variables and carries a test framework prefix — for example `pw:owner/repo-16873-1`. On a provider it does not recognise, the value is a random id. Either way a separate `currents cancel` invocation cannot recover the value — it rebuilds the CI build id from the environment, produces a different string, and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` explicitly on any job you want to cancel from CI.
 {% endhint %}
 
 ### Cancelling from GitHub Actions
@@ -76,16 +76,20 @@ playwright_tests:
     - if [ "$CI_JOB_STATUS" = "canceled" ]; then npx currents cancel; fi
 ```
 
-`CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses.
+`CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses. Set `CURRENTS_RECORD_KEY` as a **masked** CI/CD variable, and protected where the pipeline's branch policy allows it, so a job that echoes its environment cannot leak the key. `CURRENTS_PROJECT_ID` is not a secret and needs neither.
 
 GitLab runs `after_script` when a job is cancelled, which is what makes this work; there is no `when:` value that matches cancellation. `when: on_failure` in particular does not fire — it triggers on a failed job, and a cancelled job is not a failed one.
 
+{% hint style="warning" %}
+`$CI_PIPELINE_ID` is stable across all jobs in a pipeline, which is what a CI build id needs, but it does not change when an individual job is retried. Currents requires a distinct CI build id per attempt, so a retried job reports against the completed run rather than a new one. Re-run the whole pipeline, or append a value that changes per attempt to `CURRENTS_CI_BUILD_ID`. See [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention").
+{% endhint %}
+
 {% hint style="info" %}
-Force cancelling a job skips `after_script`, so those runs still end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
+`after_script` runs on cancellation from GitLab 17.0 and GitLab Runner 16.10. Earlier versions stop the job without running it. Two cases skip it on any version: a job cancelled while still pending never starts, and force cancelling terminates the job immediately. Runs cancelled those ways end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
 {% endhint %}
 
 ### Notes
 
-* Every job of a parallelized run records into the same run. Cancelling a run that is already cancelled succeeds, so it is safe for each job to run the command.
-* A run only exists once results have been recorded. Cancelling before the first results were uploaded reports that there is no run to cancel and exits successfully, so the step does not fail on an already cancelled job.
-* Cancelled runs are marked in the dashboard and trigger the usual integrations. See [cancel-run.md](../../../dashboard/runs/cancel-run.md "mention") for what cancelling a run affects.
+- Every job of a parallelized run records into the same run. Cancelling a run that is already cancelled succeeds, so it is safe for each job to run the command.
+- A run only exists once results have been recorded. Cancelling before the first results were uploaded reports that there is no run to cancel and exits successfully, so the step does not fail on an already cancelled job.
+- Cancelled runs are marked in the dashboard and trigger the usual integrations. See [cancel-run.md](../../../dashboard/runs/cancel-run.md "mention") for what cancelling a run affects.

From fb489b9549922c8de7eaff0d382c777aea36c85e Mon Sep 17 00:00:00 2001
From: Andrew Goldis 
Date: Sat, 8 Aug 2026 00:08:16 -0700
Subject: [PATCH 12/17] Correct the GitLab version requirement and heading
 levels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The version note named GitLab Runner 16.10, which is when after_script
started running on cancellation — but on 16.10 $CI_JOB_STATUS still reads
"failed" while the job is cancelling, so the guard in the example never
matches. The combination the example actually needs is GitLab 17.0 with
Runner 16.11.1, generally available in GitLab 17.3.

Headings: the page went from H1 straight to H3. I previously left this
alone on the grounds that the other files in currents-cmd/ shared the
pattern, which was the wrong reason — currents-convert.md and
currents-upload.md carry four H1s each, so the directory has no single
convention to preserve. Fixed here; the rest is a separate cleanup.

Anchors are derived from heading text, not level, so no inbound links
change. There are no #anchor references to this page in the repo either.

Co-Authored-By: Claude Opus 5 (1M context) 
Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP
---
 resources/reporters/currents-cmd/currents-cancel.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index 4948d831..995570d2 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -10,7 +10,7 @@ A cancelled CI job stops reporting mid-run, so without an explicit cancellation
 
 The command is available from `@currents/cmd` 1.10.0.
 
-### Usage
+## Usage
 
 {% hint style="info" %}
 The command authenticates with the [record-key.md](../../../guides/record-key.md "mention") the job already uses to report results — no API key is needed. It accepts `--key`, `--project-id`, `--ci-build-id` and `--run-id`, or the `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`, `CURRENTS_CI_BUILD_ID` and `CURRENTS_RUN_ID` environment variables.
@@ -20,7 +20,7 @@ The command authenticates with the [record-key.md](../../../guides/record-key.md
 npx currents cancel --key  --project-id  --ci-build-id 
 ```
 
-### Identifying the run
+## Identifying the run
 
 Pass either the [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention") the run was recorded with, or the run id:
 
@@ -38,7 +38,7 @@ Use `--run-id` when you already have the run id: it is the last segment of the r
 If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and neither of the two forms it can take is reproducible by a separate step. On a CI provider Currents recognises, the value is derived from that provider's environment variables and carries a test framework prefix — for example `pw:owner/repo-16873-1`. On a provider it does not recognise, the value is a random id. Either way a separate `currents cancel` invocation cannot recover the value — it rebuilds the CI build id from the environment, produces a different string, and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` explicitly on any job you want to cancel from CI.
 {% endhint %}
 
-### Cancelling from GitHub Actions
+## Cancelling from GitHub Actions
 
 A job that already exports the record key, project and CI build id needs no arguments:
 
@@ -61,7 +61,7 @@ jobs:
 
 Declaring them on the job rather than on each step is what makes "no arguments" work: a step's `env` is visible only to that step.
 
-### Cancelling from other CI providers
+## Cancelling from other CI providers
 
 The command only needs the record key, the project and the CI build id, so the same step works anywhere. Set the CI build id for the whole pipeline, so the reporting job and the cancelling step use the same value. GitLab CI, for example:
 
@@ -85,10 +85,10 @@ GitLab runs `after_script` when a job is cancelled, which is what makes this wor
 {% endhint %}
 
 {% hint style="info" %}
-`after_script` runs on cancellation from GitLab 17.0 and GitLab Runner 16.10. Earlier versions stop the job without running it. Two cases skip it on any version: a job cancelled while still pending never starts, and force cancelling terminates the job immediately. Runs cancelled those ways end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
+The example needs GitLab 17.0 with GitLab Runner 16.11.1, which is the combination where `$CI_JOB_STATUS` reads `canceled` while `after_script` runs; it became generally available in GitLab 17.3. GitLab Runner 16.10 already ran `after_script` on cancellation, but reported the status as `failed`, so the guard above would never match. Two cases skip `after_script` on every version: a job cancelled while still pending never starts, and force cancelling terminates the job immediately. Runs cancelled either way end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
 {% endhint %}
 
-### Notes
+## Notes
 
 - Every job of a parallelized run records into the same run. Cancelling a run that is already cancelled succeeds, so it is safe for each job to run the command.
 - A run only exists once results have been recorded. Cancelling before the first results were uploaded reports that there is no run to cancel and exits successfully, so the step does not fail on an already cancelled job.

From 5114ae0659db0f0258b05d749ae855775ad48307 Mon Sep 17 00:00:00 2001
From: Andrew Goldis 
Date: Sat, 8 Aug 2026 00:25:25 -0700
Subject: [PATCH 13/17] Make the GitLab retry guidance specific about scope
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous wording — "append a value that changes per attempt" — did not
say where to set it. Applying a discriminator to the reporting command
alone leaves after_script reading the unsuffixed pipeline-level value, so
the cancel would look for a different run than the one recorded. The note
now says to set it in variables:, where both script and after_script read
it, and gives the two real options: $CI_JOB_ID when one job reports the
whole run, or re-running the pipeline when the run is split across
parallel jobs, since GitLab has no variable that is both per-attempt and
shared by every job.

Also link the GitHub Actions snippet to cancel-runs.md. The snippet grew a
jobs: wrapper in this PR so it could show job-scoped env, which brought it
closer to the full workflow on that page; naming one page as the one to
change keeps them from drifting.

Co-Authored-By: Claude Opus 5 (1M context) 
Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP
---
 resources/reporters/currents-cmd/currents-cancel.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index 995570d2..f800e25d 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -61,6 +61,8 @@ jobs:
 
 Declaring them on the job rather than on each step is what makes "no arguments" work: a step's `env` is visible only to that step.
 
+The snippet above is trimmed to the parts that matter for cancelling. [cancel-runs.md](../../../getting-started/ci-setup/github-actions/cancel-runs.md "mention") holds the complete workflow — checkout, setup, `concurrency` — and is the page to change when the workflow itself changes.
+
 ## Cancelling from other CI providers
 
 The command only needs the record key, the project and the CI build id, so the same step works anywhere. Set the CI build id for the whole pipeline, so the reporting job and the cancelling step use the same value. GitLab CI, for example:
@@ -81,7 +83,11 @@ playwright_tests:
 GitLab runs `after_script` when a job is cancelled, which is what makes this work; there is no `when:` value that matches cancellation. `when: on_failure` in particular does not fire — it triggers on a failed job, and a cancelled job is not a failed one.
 
 {% hint style="warning" %}
-`$CI_PIPELINE_ID` is stable across all jobs in a pipeline, which is what a CI build id needs, but it does not change when an individual job is retried. Currents requires a distinct CI build id per attempt, so a retried job reports against the completed run rather than a new one. Re-run the whole pipeline, or append a value that changes per attempt to `CURRENTS_CI_BUILD_ID`. See [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention").
+`$CI_PIPELINE_ID` is stable across every job in a pipeline, which is what a CI build id needs, but it does not change when an individual job is retried. Currents requires a distinct CI build id per attempt, so a retried job reports against the completed run rather than a new one.
+
+Whatever value you choose, set it in `variables:` as above. Both `script` and `after_script` read `CURRENTS_CI_BUILD_ID` from the job's environment, so a discriminator applied to the reporting command alone would leave `currents cancel` looking for a different run than the one that was recorded.
+
+If a single job reports the whole run, `$CI_JOB_ID` changes on every retry and works. If the run is split across parallel jobs, no GitLab variable is both per-attempt and shared by all of them — re-run the pipeline instead, which yields a new `$CI_PIPELINE_ID`. See [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention").
 {% endhint %}
 
 {% hint style="info" %}

From 2a93dc4b574fb0e0649a08e18b65dd510c4897ab Mon Sep 17 00:00:00 2001
From: Andrew Goldis 
Date: Sat, 8 Aug 2026 00:50:29 -0700
Subject: [PATCH 14/17] Rewrite the cancel docs prose in the Currents voice

The wording I added over the review rounds drifted from the house style.
Applied the brand kit and humanizer rules to my own sentences only:

- Removed every em dash from the prose I wrote. The brand kit rules them
  out; commas and full stops cover all six cases.
- Split the long sentences. The CI build id warning ran four clauses deep
  before it reached the point.
- Dropped the "which is what a CI build id needs" construction, which had
  crept into three separate paragraphs.
- Second person where the reader is the one acting: "whatever value you
  pick", "your branch policy", "set it yourself".
- Dropped the bold on masked. GitLab's setting is called Masked, so the
  word carries itself.

No technical content changed. Version numbers, variable names and the
GitLab behaviour all read the same as before.

Pre-existing em dashes in these files are untouched; they are not mine to
rewrite in this PR.

Co-Authored-By: Claude Opus 5 (1M context) 
Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP
---
 dashboard/runs/cancel-run.md                   |  5 ++---
 .../ci-setup/github-actions/cancel-runs.md     |  2 +-
 .../reporters/currents-cmd/currents-cancel.md  | 18 +++++++++---------
 3 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md
index 96100c69..6bfd6e57 100644
--- a/dashboard/runs/cancel-run.md
+++ b/dashboard/runs/cancel-run.md
@@ -110,9 +110,8 @@ The action also accepts an [api-keys.md](../administration/api-keys.md "mention"
 
 Pass `project-id` and `ci-build-id` as well to identify the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") instead — which is what you need when the workflow records under a CI build ID of its own:
 
-Declare the variables on the job, not on the reporting step — a step's `env`
-is not visible to any other step, so the cancelling step would read them as
-empty:
+Declare the variables on the job, not on the reporting step. A step's `env` is
+visible only to that step, so the cancelling step would read them as empty:
 
 ```yaml
 jobs:
diff --git a/getting-started/ci-setup/github-actions/cancel-runs.md b/getting-started/ci-setup/github-actions/cancel-runs.md
index 1fb6f4c4..4aa45eaf 100644
--- a/getting-started/ci-setup/github-actions/cancel-runs.md
+++ b/getting-started/ci-setup/github-actions/cancel-runs.md
@@ -32,7 +32,7 @@ The [cancel-run-gh-action](https://github.com/currents-dev/cancel-run-gh-action)
   uses: currents-dev/cancel-run-gh-action@v1
 ```
 
-With no inputs it reads `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` from the job's environment, the way the full example below declares them. Declaring them on the reporting step instead leaves them empty here, since a step's `env` is visible only to that step. Like the command, it can also identify the run by its run id — the `run-id` input, or `CURRENTS_RUN_ID`. See the [action's README](https://github.com/currents-dev/cancel-run-gh-action#inputs) for every input.
+With no inputs it reads `CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID` and `CURRENTS_CI_BUILD_ID` from the job's environment, the way the full example below declares them. Declare them on the reporting step instead and they arrive empty here, because a step's `env` is visible only to that step. Like the command, it can also identify the run by its run id — the `run-id` input, or `CURRENTS_RUN_ID`. See the [action's README](https://github.com/currents-dev/cancel-run-gh-action#inputs) for every input.
 
 ## Full example
 
diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index f800e25d..a61aadf7 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -35,7 +35,7 @@ Use `--ci-build-id` for cancelling from CI. Set `CURRENTS_CI_BUILD_ID` on the jo
 Use `--run-id` when you already have the run id: it is the last segment of the run URL, `https://app.currents.dev/run/`. This is the option for cancelling a specific run from a script or by hand.
 
 {% hint style="warning" %}
-If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and neither of the two forms it can take is reproducible by a separate step. On a CI provider Currents recognises, the value is derived from that provider's environment variables and carries a test framework prefix — for example `pw:owner/repo-16873-1`. On a provider it does not recognise, the value is a random id. Either way a separate `currents cancel` invocation cannot recover the value — it rebuilds the CI build id from the environment, produces a different string, and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` explicitly on any job you want to cancel from CI.
+If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and a separate step cannot reproduce either form it takes. On a CI provider Currents detects, the value comes from that provider's environment variables and carries a test framework prefix, such as `pw:owner/repo-16873-1`. On any other provider it is a random id. Either way `currents cancel` rebuilds the id from the environment, gets a different string, and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` yourself on any job you want to cancel from CI.
 {% endhint %}
 
 ## Cancelling from GitHub Actions
@@ -59,9 +59,9 @@ jobs:
         run: npx currents cancel
 ```
 
-Declaring them on the job rather than on each step is what makes "no arguments" work: a step's `env` is visible only to that step.
+Declaring them on the job is what lets the cancel step run with no arguments. A step's `env` is visible only to that step.
 
-The snippet above is trimmed to the parts that matter for cancelling. [cancel-runs.md](../../../getting-started/ci-setup/github-actions/cancel-runs.md "mention") holds the complete workflow — checkout, setup, `concurrency` — and is the page to change when the workflow itself changes.
+The snippet above is trimmed to the parts that matter for cancelling. [cancel-runs.md](../../../getting-started/ci-setup/github-actions/cancel-runs.md "mention") holds the complete workflow, including checkout, setup and `concurrency`. Change that page when the workflow itself changes.
 
 ## Cancelling from other CI providers
 
@@ -78,20 +78,20 @@ playwright_tests:
     - if [ "$CI_JOB_STATUS" = "canceled" ]; then npx currents cancel; fi
 ```
 
-`CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses. Set `CURRENTS_RECORD_KEY` as a **masked** CI/CD variable, and protected where the pipeline's branch policy allows it, so a job that echoes its environment cannot leak the key. `CURRENTS_PROJECT_ID` is not a secret and needs neither.
+`CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses. Set `CURRENTS_RECORD_KEY` as a masked CI/CD variable, and protected where your branch policy allows it. Any job that echoes its environment would otherwise print the key. `CURRENTS_PROJECT_ID` is not a secret and needs neither.
 
-GitLab runs `after_script` when a job is cancelled, which is what makes this work; there is no `when:` value that matches cancellation. `when: on_failure` in particular does not fire — it triggers on a failed job, and a cancelled job is not a failed one.
+This works because GitLab runs `after_script` when a job is cancelled. No `when:` value matches cancellation. `when: on_failure` does not fire either: it triggers on a failed job, and a cancelled job is not a failed one.
 
 {% hint style="warning" %}
-`$CI_PIPELINE_ID` is stable across every job in a pipeline, which is what a CI build id needs, but it does not change when an individual job is retried. Currents requires a distinct CI build id per attempt, so a retried job reports against the completed run rather than a new one.
+A CI build id has to stay the same across every job in a pipeline, and `$CI_PIPELINE_ID` does. It does not change when you retry a single job. Currents requires a distinct CI build id per attempt, so a retried job reports against the completed run instead of a new one.
 
-Whatever value you choose, set it in `variables:` as above. Both `script` and `after_script` read `CURRENTS_CI_BUILD_ID` from the job's environment, so a discriminator applied to the reporting command alone would leave `currents cancel` looking for a different run than the one that was recorded.
+Whatever value you pick, set it in `variables:` as above. Both `script` and `after_script` read `CURRENTS_CI_BUILD_ID` from the job's environment. Add the discriminator to the reporting command alone and `currents cancel` looks for a different run than the one you recorded.
 
-If a single job reports the whole run, `$CI_JOB_ID` changes on every retry and works. If the run is split across parallel jobs, no GitLab variable is both per-attempt and shared by all of them — re-run the pipeline instead, which yields a new `$CI_PIPELINE_ID`. See [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention").
+If a single job reports the whole run, use `$CI_JOB_ID`. It changes on every retry. If the run is split across parallel jobs, no GitLab variable is both per-attempt and shared by all of them, so re-run the pipeline instead. That gives you a new `$CI_PIPELINE_ID`. See [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention").
 {% endhint %}
 
 {% hint style="info" %}
-The example needs GitLab 17.0 with GitLab Runner 16.11.1, which is the combination where `$CI_JOB_STATUS` reads `canceled` while `after_script` runs; it became generally available in GitLab 17.3. GitLab Runner 16.10 already ran `after_script` on cancellation, but reported the status as `failed`, so the guard above would never match. Two cases skip `after_script` on every version: a job cancelled while still pending never starts, and force cancelling terminates the job immediately. Runs cancelled either way end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
+The example needs GitLab 17.0 with GitLab Runner 16.11.1. That is the first combination where `$CI_JOB_STATUS` reads `canceled` while `after_script` runs, and it became generally available in GitLab 17.3. Runner 16.10 already ran `after_script` on cancellation, but reported the status as `failed`, so the guard above never matches. Two cases skip `after_script` on every version. A job cancelled while still pending never starts, and force cancelling ends the job immediately. Runs cancelled either way end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
 {% endhint %}
 
 ## Notes

From 988ca6d77557d54762bf14bd4ccfcfb871cbed19 Mon Sep 17 00:00:00 2001
From: Andrew Goldis 
Date: Sat, 8 Aug 2026 01:08:01 -0700
Subject: [PATCH 15/17] Apply the docs writing rules to the cancel pages

The currents-write-documentation skill exists now. Re-checked my prose
against it and found four things the brand kit does not cover:

- Two hints in a row, which the skill calls a sign the page structure is
  wrong. The version requirement was never a warning; it is a prerequisite,
  so it moves into prose next to the mechanism it constrains, leaving one
  warning hint for the retry caveat.
- Sentences opening with a bare This, It or That pointing at the previous
  idea. Five of them, most introduced when I shortened sentences last time.
  Each now names its subject.
- CI Build ID was written three ways across the docs. The dominant form is
  CI Build ID at 61 uses, so this page now uses it throughout. Normalised
  the two pre-existing lowercase instances as well, since a half-cased page
  is what the one-term-per-thing rule is meant to prevent.
- "would read them as empty" and "would otherwise print the key" are
  conditional; the docs use present tense for behavior.

Co-Authored-By: Claude Opus 5 (1M context) 
Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP
---
 .claude/settings.json                         |  5 +++++
 dashboard/runs/cancel-run.md                  |  2 +-
 .../reporters/currents-cmd/currents-cancel.md | 20 +++++++++----------
 3 files changed, 15 insertions(+), 12 deletions(-)
 create mode 100644 .claude/settings.json

diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..4623a3ad
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "currents-skills@currents-internal-skills": true
+  }
+}
diff --git a/dashboard/runs/cancel-run.md b/dashboard/runs/cancel-run.md
index 6bfd6e57..1dc57b8c 100644
--- a/dashboard/runs/cancel-run.md
+++ b/dashboard/runs/cancel-run.md
@@ -111,7 +111,7 @@ The action also accepts an [api-keys.md](../administration/api-keys.md "mention"
 Pass `project-id` and `ci-build-id` as well to identify the run by its [ci-build-id.md](../../guides/parallelization-guide/ci-build-id.md "mention") instead — which is what you need when the workflow records under a CI build ID of its own:
 
 Declare the variables on the job, not on the reporting step. A step's `env` is
-visible only to that step, so the cancelling step would read them as empty:
+visible only to that step, so the cancelling step reads them as empty:
 
 ```yaml
 jobs:
diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index a61aadf7..d4026292 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -35,12 +35,12 @@ Use `--ci-build-id` for cancelling from CI. Set `CURRENTS_CI_BUILD_ID` on the jo
 Use `--run-id` when you already have the run id: it is the last segment of the run URL, `https://app.currents.dev/run/`. This is the option for cancelling a specific run from a script or by hand.
 
 {% hint style="warning" %}
-If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and a separate step cannot reproduce either form it takes. On a CI provider Currents detects, the value comes from that provider's environment variables and carries a test framework prefix, such as `pw:owner/repo-16873-1`. On any other provider it is a random id. Either way `currents cancel` rebuilds the id from the environment, gets a different string, and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` yourself on any job you want to cancel from CI.
+If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and a separate step cannot reproduce either form the value takes. On a CI provider Currents detects, the value comes from that provider's environment variables and carries a test framework prefix, such as `pw:owner/repo-16873-1`. On any other provider the value is a random id. Either way `currents cancel` rebuilds the CI Build ID from the environment, gets a different string, and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` yourself on any job you want to cancel from CI.
 {% endhint %}
 
 ## Cancelling from GitHub Actions
 
-A job that already exports the record key, project and CI build id needs no arguments:
+A job that already exports the record key, project and CI Build ID needs no arguments:
 
 ```yaml
 jobs:
@@ -65,7 +65,7 @@ The snippet above is trimmed to the parts that matter for cancelling. [cancel-ru
 
 ## Cancelling from other CI providers
 
-The command only needs the record key, the project and the CI build id, so the same step works anywhere. Set the CI build id for the whole pipeline, so the reporting job and the cancelling step use the same value. GitLab CI, for example:
+The command only needs the record key, the project and the CI Build ID, so the same step works anywhere. Set the CI Build ID for the whole pipeline, so the reporting job and the cancelling step use the same value. GitLab CI, for example:
 
 ```yaml
 variables:
@@ -78,20 +78,18 @@ playwright_tests:
     - if [ "$CI_JOB_STATUS" = "canceled" ]; then npx currents cancel; fi
 ```
 
-`CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses. Set `CURRENTS_RECORD_KEY` as a masked CI/CD variable, and protected where your branch policy allows it. Any job that echoes its environment would otherwise print the key. `CURRENTS_PROJECT_ID` is not a secret and needs neither.
+`CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses. Set `CURRENTS_RECORD_KEY` as a masked CI/CD variable, and protected where your branch policy allows it. Masking keeps the key out of the job log. `CURRENTS_PROJECT_ID` is not a secret and needs neither.
 
-This works because GitLab runs `after_script` when a job is cancelled. No `when:` value matches cancellation. `when: on_failure` does not fire either: it triggers on a failed job, and a cancelled job is not a failed one.
+The guard works because GitLab runs `after_script` when a job is cancelled. No `when:` value matches cancellation. `when: on_failure` does not fire either: the trigger is a failed job, and a cancelled job is not a failed one.
+
+The example requires GitLab 17.0 with GitLab Runner 16.11.1, the first combination where `$CI_JOB_STATUS` reads `canceled` while `after_script` runs. GitLab 17.3 made the behavior generally available. Runner 16.10 also runs `after_script` on cancellation, but reports the status as `failed`, so the guard never matches. Two cases skip `after_script` on every version: a job cancelled while still pending never starts, and force cancelling ends the job immediately. Runs cancelled either way end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
 
 {% hint style="warning" %}
-A CI build id has to stay the same across every job in a pipeline, and `$CI_PIPELINE_ID` does. It does not change when you retry a single job. Currents requires a distinct CI build id per attempt, so a retried job reports against the completed run instead of a new one.
+A CI Build ID has to stay the same across every job in a pipeline, and `$CI_PIPELINE_ID` does. Retrying a single job does not change the value. Currents requires a distinct CI Build ID per attempt, so a retried job reports against the completed run instead of a new one.
 
 Whatever value you pick, set it in `variables:` as above. Both `script` and `after_script` read `CURRENTS_CI_BUILD_ID` from the job's environment. Add the discriminator to the reporting command alone and `currents cancel` looks for a different run than the one you recorded.
 
-If a single job reports the whole run, use `$CI_JOB_ID`. It changes on every retry. If the run is split across parallel jobs, no GitLab variable is both per-attempt and shared by all of them, so re-run the pipeline instead. That gives you a new `$CI_PIPELINE_ID`. See [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention").
-{% endhint %}
-
-{% hint style="info" %}
-The example needs GitLab 17.0 with GitLab Runner 16.11.1. That is the first combination where `$CI_JOB_STATUS` reads `canceled` while `after_script` runs, and it became generally available in GitLab 17.3. Runner 16.10 already ran `after_script` on cancellation, but reported the status as `failed`, so the guard above never matches. Two cases skip `after_script` on every version. A job cancelled while still pending never starts, and force cancelling ends the job immediately. Runs cancelled either way end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
+If a single job reports the whole run, use `$CI_JOB_ID`, which changes on every retry. If the run is split across parallel jobs, no GitLab variable is both per-attempt and shared by all of them. Re-run the pipeline instead, so the jobs get a new `$CI_PIPELINE_ID`. See [ci-build-id.md](../../../guides/parallelization-guide/ci-build-id.md "mention").
 {% endhint %}
 
 ## Notes

From 057bbe4a3b218bc30191e43973a1466447c82eee Mon Sep 17 00:00:00 2001
From: Andrew Goldis 
Date: Sat, 8 Aug 2026 01:08:56 -0700
Subject: [PATCH 16/17] Cut the CI Build ID warning down to the instruction

The hint ran five sentences and ninety words before the reader reached the
thing to do, which was the last sentence. It now opens with the
instruction, then the failure it prevents: three sentences, none over
twenty words.

Dropped the example of a generated value (pw:owner/repo-16873-1). The two
forms are still named, and the detail belongs in ci-build-id.md, which the
section above already links.

Co-Authored-By: Claude Opus 5 (1M context) 
Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP
---
 resources/reporters/currents-cmd/currents-cancel.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index d4026292..de259f74 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -35,7 +35,7 @@ Use `--ci-build-id` for cancelling from CI. Set `CURRENTS_CI_BUILD_ID` on the jo
 Use `--run-id` when you already have the run id: it is the last segment of the run URL, `https://app.currents.dev/run/`. This is the option for cancelling a specific run from a script or by hand.
 
 {% hint style="warning" %}
-If the job does not set `CURRENTS_CI_BUILD_ID`, Currents generates one, and a separate step cannot reproduce either form the value takes. On a CI provider Currents detects, the value comes from that provider's environment variables and carries a test framework prefix, such as `pw:owner/repo-16873-1`. On any other provider the value is a random id. Either way `currents cancel` rebuilds the CI Build ID from the environment, gets a different string, and reports that there is no run to cancel. Set `CURRENTS_CI_BUILD_ID` yourself on any job you want to cancel from CI.
+Set `CURRENTS_CI_BUILD_ID` on any job you want to cancel from CI. Without it, Currents generates the value from the CI environment, or at random on a provider it does not detect. `currents cancel` cannot reproduce either form, so the command reports that there is no run to cancel.
 {% endhint %}
 
 ## Cancelling from GitHub Actions

From af7683a2702b64a368755ec7fd71fc174b2e487a Mon Sep 17 00:00:00 2001
From: Andrew Goldis 
Date: Sat, 8 Aug 2026 01:10:12 -0700
Subject: [PATCH 17/17] Split the GitLab cancellation notes by topic

One paragraph carried the version requirement, the Runner 16.10 caveat,
the two cases that skip after_script, and the timeout fallback. Five
sentences, one of them explaining three separate things. Now three
paragraphs of two sentences each: how the guard works, what versions it
needs, and when it does not run.

Dropped "GitLab 17.3 made the behavior generally available". On 17.0 with
Runner 16.11.1 the guard works, so the flag's removal date does not change
what the reader does.

Co-Authored-By: Claude Opus 5 (1M context) 
Claude-Session: https://claude.ai/code/session_013vBAvmWyyJsE1eTnxXL2XP
---
 resources/reporters/currents-cmd/currents-cancel.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/resources/reporters/currents-cmd/currents-cancel.md b/resources/reporters/currents-cmd/currents-cancel.md
index de259f74..e328dff2 100644
--- a/resources/reporters/currents-cmd/currents-cancel.md
+++ b/resources/reporters/currents-cmd/currents-cancel.md
@@ -80,9 +80,11 @@ playwright_tests:
 
 `CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` come from the pipeline's variables, the same ones the reporting job uses. Set `CURRENTS_RECORD_KEY` as a masked CI/CD variable, and protected where your branch policy allows it. Masking keeps the key out of the job log. `CURRENTS_PROJECT_ID` is not a secret and needs neither.
 
-The guard works because GitLab runs `after_script` when a job is cancelled. No `when:` value matches cancellation. `when: on_failure` does not fire either: the trigger is a failed job, and a cancelled job is not a failed one.
+The guard relies on GitLab running `after_script` on cancellation. No `when:` value matches a cancelled job, including `when: on_failure`, which fires only on failure.
 
-The example requires GitLab 17.0 with GitLab Runner 16.11.1, the first combination where `$CI_JOB_STATUS` reads `canceled` while `after_script` runs. GitLab 17.3 made the behavior generally available. Runner 16.10 also runs `after_script` on cancellation, but reports the status as `failed`, so the guard never matches. Two cases skip `after_script` on every version: a job cancelled while still pending never starts, and force cancelling ends the job immediately. Runs cancelled either way end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
+Cancelling from `after_script` requires GitLab 17.0 with GitLab Runner 16.11.1, the first versions where `$CI_JOB_STATUS` reads `canceled`. Runner 16.10 runs `after_script` on cancellation but reports `failed`, so the guard never matches.
+
+Two cases skip `after_script` on any version: a job cancelled while still pending, and a force cancelled job. Those runs end at the [run-timeouts.md](../../../dashboard/runs/run-timeouts.md "mention") instead.
 
 {% hint style="warning" %}
 A CI Build ID has to stay the same across every job in a pipeline, and `$CI_PIPELINE_ID` does. Retrying a single job does not change the value. Currents requires a distinct CI Build ID per attempt, so a retried job reports against the completed run instead of a new one.