-
Notifications
You must be signed in to change notification settings - Fork 0
[ENG-1012] docs: cancelling runs from CI #60
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+232
−29
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
41fd53e
docs: add currents cancel
agoldis 5179ece
docs: document run cancellation on GitHub Actions
agoldis 255b916
Merge origin/main into docs/currents-cancel
agoldis ead8c7d
docs: cancel a run by its run id
agoldis 23050be
docs: the cancel action also accepts a run id
agoldis 500723f
docs: use the repo-prefixed CI build id in the cancel examples
agoldis 9f2259b
docs: name the run ID alongside the CI build ID
agoldis bc72efe
docs: name the version currents cancel ships in
agoldis 5873f5e
docs: keep the API key section at the same level as its siblings
agoldis File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| --- | ||
| 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") 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. | ||
| {% 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 | ||
| - 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. 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. | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
|
|
||
| ## 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| 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"). | ||
|
|
||
| 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 | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
|
|
||
| {% 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. | ||
| {% endhint %} | ||
|
|
||
| ```bash | ||
| npx currents cancel --key <record-key> --project-id <project-id> --ci-build-id <ci-build-id> | ||
| ``` | ||
|
|
||
| ### 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 <record-key> --project-id <project-id> --run-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 }}` — 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/<run-id>`. 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 | ||
|
|
||
| A job that already exports the record key, project and CI build id needs no arguments: | ||
|
|
||
| ```yaml | ||
|
agoldis marked this conversation as resolved.
|
||
| - 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 | ||
| ``` | ||
|
|
||
| ### 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: | ||
|
|
||
| ```yaml | ||
| variables: | ||
| CURRENTS_CI_BUILD_ID: $CI_PIPELINE_ID | ||
|
|
||
| cancel_currents_run: | ||
| stage: .post | ||
| when: on_failure | ||
| script: | ||
| - npx currents cancel | ||
| ``` | ||
|
agoldis marked this conversation as resolved.
|
||
|
|
||
| `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. | ||
| * 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. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.