# Cancel or re-run a run

Stop a run that has not finished, or start the same workflow again at the same commit.

Replace run-id with the run's id (`dcloud ci runs list` shows it).

## Prerequisites

- To cancel, `ci:CancelRun` on the run's repository (`rn:ews::<organization id>:ci:repository/<repository id>`).
- To re-run, `ci:RerunWorkflow` on the run's repository.
- In the console, also `git:GetRepository` and `ci:ListRuns` on the repository to open its **CI**
  tab, and `ci:GetRun` to open a run; without them the page is not found. The
  organization-wide **Runs** page (which needs `ci:ListRuns` on all of CI, `rn:ews::<organization id>:ci:*`)
  offers **Cancel** and **Re-run** for selected runs; without the action on all of CI they answer
  "Cancelling a run needs ci:CancelRun. Ask an administrator." or "Re-running a workflow needs
  ci:RerunWorkflow. Ask an administrator."

## Cancel a run

A run can be cancelled while it is queued, provisioning or running.

**Console**
1. Open the repository, then open its **CI** tab.
2. Open the run.
3. Choose **Cancel run**.

Without the permission the run's header says "Cancelling this run needs ci:CancelRun." instead of
showing the button.

**CLI**
```sh
dcloud ci runs cancel run-id
```

**API**
```http
POST /ci/api/runs/run-id/cancel
```

The run turns `cancelled` with the reason "Cancelled from the console", whichever interface you
used. A platform machine running it is torn down, and a self-hosted runner that has not fetched
the run's plan yet never starts it.

`409` "Run is already succeeded" (or `failed`, `cancelled`, `timed_out`) answers a run that has
already finished. `404` answers a run that is not in your organization.

## Re-run a run

A re-run is a new run of the same workflow at the same commit. It is planned from the workflow
source the original run used, not from the file as it is now, and it carries the same trigger,
ref, event and triggering user as the original. You are recorded as the person who re-ran it; that
grants the new run nothing of yours, so a re-run of someone else's run gets the secrets that
person's run would get, not yours.

**Console**
1. Open the repository, then open its **CI** tab.
2. Open the run.
3. Choose **Re-run**.

The console offers **Re-run** only for a finished run, and opens the new run once it is queued.
When the run's error asks you to re-run the workflow, **Re-run** sits in that error banner instead
of the header. Without the permission the header says "Re-running this workflow needs
ci:RerunWorkflow."

**CLI**
```sh
dcloud ci runs rerun run-id
```

**API**
```http
POST /ci/api/runs/run-id/rerun
```

The API also re-runs a run that is still in progress; the original keeps running.

The answer is `200` with the new run, `queued`, whose `rerunOfRunId` names the original. In the
run list it reads "(re-run)".

`400` "Workflow is invalid: …" answers a run whose stored workflow no longer plans. `404` answers a
run that is not in your organization.

## Related

- [Watch a run](watch-a-run.md)
- [Workflows and runs](workflows-and-runs.md)
- `ci.runs.cancel` · `ci.runs.rerun`
