Manage workflow runs

You can trigger, check status, retry, rerun, and cancel Depot CI workflow runs from the Depot dashboard, the Depot CLI, or programmatically through the Depot CI API.

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:

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 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:

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 or run depot ci dispatch --help. You can also use depot ci dispatch to trigger a workflow automatically from another workflow.

Manually trigger a workflow from the dashboard

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

Go to Depot CI and click Run a workflow.
Select a repository, an optional branch or tag, and the workflow to run.
Fill in inputs defined by the workflow, if any.
Click Run workflow.

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

Trigger workflows from other workflows

You can call depot ci dispatch from a running Depot CI job to start another workflow. Use a Depot organization or user API token for the dispatch request and pass it explicitly with --token.

Depot CI injects a built-in DEPOT_TOKEN into each job, but that token only works for the current job attempt. It can't start new workflow runs. You also can't use the job's OIDC token directly to authorize depot ci dispatch.

Store the API token as a Depot CI secret under a non-reserved name, such as DEPOT_ORG_TOKEN, then pass it to the command:

jobs:
  dispatch:
    runs-on: depot-ubuntu-latest
    steps:
      - name: Dispatch downstream workflow
        run: |
          depot ci dispatch \
            --repo depot/demo-app \
            --workflow downstream.yml \
            --ref main \
            --input upstream_run_id="$GITHUB_RUN_ID" \
            --token "$DEPOT_ORG_TOKEN"
        env:
          DEPOT_ORG_TOKEN: ${{ secrets.DEPOT_ORG_TOKEN }}

If you use a user API token and belong to multiple Depot organizations, include --org <org-id>.

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:

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:

depot ci status <run-id>

For usage, see the depot ci run list and 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:

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

Retry every failed and cancelled job in the workflow:

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 or run depot ci retry --help.

Retry a failed job from the dashboard

Go to Depot CI and click on the workflow.
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).

Rerun a workflow from the CLI

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 or run depot ci rerun --help.

Rerun a workflow from the dashboard

Go to Depot CI and click on the workflow.
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:

depot ci cancel <run-id>

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

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

Cancel a single job with --job:

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

For usage, see the depot ci cancel docs or run depot ci cancel --help.

Cancel a workflow or job from the dashboard

Go to Depot CI and click on the workflow.
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.