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 changes you're actively working on without pushing them to your repository.

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

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

The CLI detects the repository from your git remotes. Use --forge github, --forge origin, --forge entire, or --forge depot to select a forge explicitly. Use --repo to select a repository. Entire names include the namespace, such as et/acme/api. See Repository selection for detection rules.

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 detects them and uploads a patch. Jobs with an actions/checkout step for your repository apply it after checkout, including jobs in same-repository reusable workflows. If the patch cannot be downloaded or applied, the job fails. 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.

If a reusable workflow stored in another repository checks out your code, local runs report an error. Push your changes and run CI from that commit instead.

In a reusable workflow, if checkout is inside a composite action with continue-on-error, move checkout into a separate step or remove continue-on-error. This prevents the action from hiding a failed patch application.

Use the latest Depot CLI for local runs. Older versions may not support local changes in reusable workflows, or may still print a warning about them.

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

For Origin and Entire repositories, see the Origin integration and Entire integration. Use the full repository name with --repo. Dispatch uses the workflow's registered forge and does not accept --forge.

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.

1. Go to Depot CI 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.

Identify who triggered a run

The depot context identifies the authenticated Depot identity behind a run. Depot resolves it from the dispatching credential, so a caller can't set it to someone else:

Dispatches from the dashboard and with a user API token resolve to that user. Dispatches with an organization token resolve to the token, with an empty email.

github.actor and github.triggering_actor keep their GitHub meaning and aren't affected.

The same values are set as the DEPOT_ACTOR_KIND, DEPOT_ACTOR_ID, DEPOT_ACTOR_EMAIL, DEPOT_ACTOR_NAME, DEPOT_TRIGGERING_ACTOR_KIND, DEPOT_TRIGGERING_ACTOR_ID, DEPOT_TRIGGERING_ACTOR_EMAIL, and DEPOT_TRIGGERING_ACTOR_NAME environment variables.

The depot context is available in job-level if: conditions and in steps:

jobs:
  deploy:
    if: depot.actor.kind == 'user'
    runs-on: depot-ubuntu-24.04
    steps:
      - run: ./notify-slack.sh "${{ depot.triggering_actor.email }}"

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 list workflows rather than runs, use depot ci workflow list. It takes the same filters plus --name:

depot ci workflow list --name deploy --status failed

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

depot ci status <run-id>

To wait for the run to complete, add --wait:

depot ci status <run-id> --wait

The command exits with code 0 when the run finishes successfully. It exits with code 1 when the run fails or is cancelled.

For a single run's metadata, use depot ci run show <run-id>. For one workflow's jobs and per-job attempts, use depot ci workflow show <workflow-id>.

For usage, see the depot ci run list, depot ci workflow 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 single failed or cancelled job, or retry all failed and cancelled jobs in a workflow. A workflow-level retry also reruns all downstream 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

If you retry every failed job, Depot also reruns any jobs downstream of them, including succeeded and skipped jobs.

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.

Retried and rerun jobs see whoever started the retry as depot.triggering_actor, while depot.actor stays the identity that created the run. See Identify who triggered a run.

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

Retry a failed job from the dashboard

1. Go to Depot CI 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 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

1. Go to Depot CI 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 the failed and cancelled jobs plus all downstream jobs, click Re-run failed.

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

1. Go to Depot CI 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.