> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/resources/reporters/currents-cmd/currents-cancel.md). # currents run cancel Cancel a Currents run from CI, for example when the CI job is cancelled, with the currents run cancel command `currents run 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](/dashboard/runs/run-timeouts.md). ## Usage {% hint style="info" %} The command authenticates with the [Record Key](/guides/record-key.md) the job already uses to report results, so it needs no API key. The command 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 run cancel --key --project-id --ci-build-id ``` ## Identifying the run Pass either the [CI Build ID](/guides/parallelization-guide/ci-build-id.md) the run was recorded with, or the run id: ```bash npx currents run 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.repository }}-${{ github.run_id }}-${{ github.run_attempt }}`. The reporting step and the cancelling step then 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" %} 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 run cancel` cannot reproduce either form, so the command reports that there is no run to cancel. {% endhint %} ## Cancelling from GitHub Actions A job that already exports the record key, project and CI Build ID needs no arguments: ```yaml 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 --package @currents/cmd@2 currents run cancel ``` 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. `npx --package @currents/cmd@2` runs `@currents/cmd` 2.x in a project that does not install it, such as a Playwright project, and in a project that installs 1.x, which has no `run cancel`. In a project that installs 2.x, `npx currents run cancel` is enough. The snippet above is trimmed to the parts that matter for cancelling. [Cancel Runs on Workflow Cancellation](/getting-started/ci-setup/github-actions/cancel-runs.md) holds the complete workflow, including checkout, setup and `concurrency`. Change that page 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: ```yaml variables: CURRENTS_CI_BUILD_ID: $CI_PIPELINE_ID playwright_tests: script: - npx playwright test after_script: - if [ "$CI_JOB_STATUS" = "canceled" ]; then npx --package @currents/cmd@2 currents run 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. Masking keeps the key out of the job log. `CURRENTS_PROJECT_ID` is not a secret and needs neither. 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. 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](/dashboard/runs/run-timeouts.md) 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. 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 run cancel` looks for a different run than the one you recorded. 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](/guides/parallelization-guide/ci-build-id.md). {% 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 [Cancelling Runs](/dashboard/runs/cancel-run.md) for what cancelling a run affects. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.currents.dev/resources/reporters/currents-cmd/currents-cancel.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.