# Manage workflow runs (https://depot.dev/docs/ci/how-to-guides/manage-workflow-runs)

You can trigger, check status, retry, rerun, and cancel Depot CI workflow runs from the Depot dashboard, the [Depot CLI](/docs/cli/reference/depot-ci), or programmatically through the [Depot CI API](/docs/api/ci/reference).

## Run workflows with local changes

You can run a workflow locally to test it against changes you're actively working on. You don't need to push to GitHub.

Run any workflow locally with `depot ci run`. For example:

```shell
depot ci run --workflow .depot/workflows/ci.yml
```

To run a specific job, use the `--job` flag.

For usage, see the [`depot ci run` docs](/docs/cli/reference/depot-ci#depot-ci-run) or run `depot ci run --help`.

#### How local workflow runs work

When you run `depot ci run` with local changes, the CLI automatically detects the changes and uploads a patch. For any job that has an `actions/checkout` step, the CLI injects a step into each job to apply that patch after checkout. The run reflects your local state without requiring a push. For branches that exist on the remote, the patch contains only unpushed changes. For local-only branches, the patch is relative to the default branch.

Each time you run `depot ci run` locally, the CLI uploads a fresh patch, so you can keep iterating until the workflow passes.

## Manually trigger workflows

You can manually trigger workflows that include the `workflow_dispatch` event in the `on` section of the workflow YAML file.

### Manually trigger a workflow from the CLI

To run a workflow that uses an `on.workflow_dispatch` trigger, use `depot ci dispatch`. Inputs are validated against the workflow's declared input schema. For example:

```shell
depot ci dispatch --repo depot/cli --workflow deploy.yml --ref main \
  --input environment=staging --input dry_run=true
```

The `--workflow` flag takes the workflow file's basename (for example `deploy.yml`), not the full `.depot/workflows/deploy.yml` path.

The command outputs the run ID and a link to the Depot dashboard. Use `--output json` to get structured output.

For usage, see the [`depot ci dispatch` docs](/docs/cli/reference/depot-ci#depot-ci-dispatch) or run `depot ci dispatch --help`.

### Manually trigger a workflow from the dashboard

You can start workflows with an `on.workflow_dispatch` trigger from the Depot dashboard.

1. Go to [Depot CI](https://depot.dev/orgs/_/workflows) and click **Run a workflow**.
2. Select a repository, an optional branch or tag, and the workflow to run.
3. Fill in inputs defined by the workflow, if any.
4. Click **Run workflow**.

If you don't specify a branch or tag, the workflow runs against the repository's default branch.

## Find and check runs

You can list recent runs and inspect a run's workflows, jobs, and attempts from the CLI.

List recent runs with `depot ci run list`, optionally filtered. For example, to list only failed runs:

```shell
depot ci run list --status failed
```

The `--status` flag is repeatable and accepts `queued`, `running`, `finished`, `failed`, and `cancelled`.

You can also filter by `--repo`, `--sha`, `--trigger`, and `--pr` (requires `--repo`), limit results with `-n` (default 50), and get structured output with `--output json`.

To check a run's workflows, jobs, and attempt IDs, use `depot ci status`:

```shell
depot ci status <run-id>
```

For usage, see the [`depot ci run list`](/docs/cli/reference/depot-ci#depot-ci-run-list) and [`depot ci status`](/docs/cli/reference/depot-ci#depot-ci-status) docs, or run `depot ci run list --help` and `depot ci status --help`.

## Retry failed jobs

You can retry a failed or cancelled job, or every failed and cancelled job in a workflow, without rerunning the successful jobs.

### Retry a failed job from the CLI

Retry a single job:

```shell
depot ci retry <run-id> --job <job-id>
```

Retry every failed and cancelled job in the workflow:

```shell
depot ci retry <run-id> --failed
```

Include the `--workflow <workflow-id>` flag for runs with multiple workflows.

Each retry creates a new attempt. You can see previous attempts with `depot ci status`.

For usage, see the [`depot ci retry` docs](/docs/cli/reference/depot-ci#depot-ci-retry) or run `depot ci retry --help`.

### Retry a failed job from the dashboard

1. Go to [Depot CI](https://depot.dev/orgs/_/workflows) and click on the workflow.
2. Click **Retry job** for the job you want to retry.

Depot creates a new attempt for that job and queues it immediately. The rest of the workflow continues to run.

## Rerun workflows

After a workflow finishes, you can rerun every job in the workflow from scratch, or retry only the failed and cancelled jobs. See [Retry failed jobs](#retry-failed-jobs)).

### Rerun a workflow from the CLI

```shell
depot ci rerun <run-id>
```

For multi-workflow runs, pass `--workflow <id>` to select which workflow to rerun. A workflow must be in a terminal state (finished, failed, or cancelled) before it can be rerun — cancel it first if it's still running.

For usage, see the [`depot ci rerun` docs](/docs/cli/reference/depot-ci#depot-ci-rerun) or run `depot ci rerun --help`.

### Rerun a workflow from the dashboard

1. Go to [Depot CI](https://depot.dev/orgs/_/workflows) and click on the workflow.
2. Do one of the following:
   * To reset every job to queued and run the entire workflow from scratch, click **Re-run workflow**.
   * To retry only the failed and cancelled jobs, along with any skipped jobs that depend on them, click **Re-run failed**. Jobs that already succeeded aren't retried.

## Cancel runs, workflows, or jobs

You can cancel a queued or running run, an entire workflow (and all its jobs), or a single job.

### Cancel a run, workflow, or job from the CLI

With no scope flags, `depot ci cancel` cancels the entire run:

```shell
depot ci cancel <run-id>
```

Cancel an entire workflow and all jobs within it with `--workflow`:

```shell
depot ci cancel <run-id> --workflow <workflow-id>
```

Cancel a single job with `--job`:

```shell
depot ci cancel <run-id> --job <job-id>
```

For usage, see the [`depot ci cancel` docs](/docs/cli/reference/depot-ci#depot-ci-cancel) or run `depot ci cancel --help`.

### Cancel a workflow or job from the dashboard

1. Go to [Depot CI](https://depot.dev/orgs/_/workflows) and click on the workflow.
2. Do one of the following:
   * To cancel a single job, click **Cancel job** next to that job.
   * To cancel the entire workflow, click **Cancel workflow**. This cancels all queued and running jobs in the workflow.

## For AI Agents

The full site index is at [llms.txt](https://depot.dev/llms.txt). Append `.md` to any documentation, blog, changelog, or customer URL to fetch its markdown source directly.