---
title: "Run"
method: POST
path: "/depot.ci.v1.CIService/Run"
tags: ["CIService"]
---

# Run

`POST /depot.ci.v1.CIService/Run`

## Request

- Base URL: `https://api.depot.dev`
- URL: `https://api.depot.dev/depot.ci.v1.CIService/Run`
- Auth: HTTP bearer

Triggers a CI run. Runs can contain one or more workflows.

## Headers

- `Connect-Protocol-Version` 1, required: Define the version of the Connect protocol
- `Connect-Timeout-Ms` number: Define the timeout, in ms

## Request body

- DepotCiV1RunRequest
  - `repo` string, required: Repository to run workflows from. GitHub, Origin, and Entire repositories use `owner/name` format. For example, "depot/cli". For Entire, use the `owner/name` in the repository's clone URL. Depot Code repositories use the repository name. For example, "widgets".
  - `sha` string, nullable: Commit SHA to run against. Use a specific commit to run a particular version of your workflow files (and have that SHA appear in github.sha), or omit to run the latest commit on the default branch. Must be a full 40-character hex SHA. Default: HEAD of the default branch.
  - `workflow` string, nullable: Path of the workflow file to run, relative to the repo root. For example, ".depot/workflows/ci.yml". Mutually exclusive with `workflowContent`; if neither is provided, runs all workflows in the repo.
  - `workflowContent` string[]: An array of workflow YAMLs to run. Depot reads the YAML from the request instead of the repo. Each entry must be the complete content of a workflow (as found in `.depot/workflows/`). Useful for testing workflow YAML changes without committing them. Mutually exclusive with `workflow`; if neither is provided, runs all workflows in the repo.
  - `job` string, nullable: Job key of a single job to run from within a workflow. For example, "build" or "test". When specified, the run skips all other jobs in the workflow. Valid only when a single workflow is specified, either through `workflow` or a `workflowContent` entry containing one workflow.
  - `forge` 'FORGE_UNSPECIFIED' | 'FORGE_GITHUB' | 'FORGE_ORIGIN' | 'FORGE_DEPOT_CODE' | 'FORGE_ENTIRE'
  - `ref` string, nullable: Branch or tag the `sha` was checked out from, used to attribute test results. For example, "refs/heads/feature". An unqualified name like "feature" is treated as a branch. To use a tag, pass the fully-qualified ref "refs/tags/v1.0". It does not change what is checked out. Only valid when `sha` is set.

## Response `200`

Success

- DepotCiV1RunResponse
  - `orgId` string: Depot organization that owns this run.
  - `runId` string: Unique identifier for the created CI run. Use it for methods like `GetRun`, `GetRunStatus`, `CancelRun`, and `ListArtifacts` to track, cancel, or fetch results from the run.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/depot/apis/depot-ci-api.md) - [All operations](https://skmtc.dev/depot/apis/depot-ci-api/llms.txt) - [OpenAPI document](https://skmtc.dev/depot/apis/depot-ci-api/revisions/6cf759b535b4?raw)