Depot CI API reference
RPC-first reference for the Depot CI Connect API. Every method is generated from the OpenAPI artifact and grouped by CI resource. The Depot CI API exposes a four-level resource hierarchy.
- Run: Top-level execution unit triggered by an event or workflow dispatch. Contains one or more workflows.
- Workflow: Corresponds to a single workflow YAML file. Contains one or more jobs.
- Job: Corresponds to one entry in the workflow YAML. Has one or more attempts.
- Attempt: One dispatch of a job. Retries create new attempts.
Logs, metrics, artifacts, and failure diagnoses are scoped to attempts but reachable from the parent run, workflow, or job.
Secret and variable management methods use the depot.ci.v3beta2 package. This API surface is in beta and may change.
RPC basics
Base URL
https://api.depot.devProtocol
Connect RPC over HTTPEncoding
JSON or Connect JSONMethod index
The Depot CI API provides the following methods, grouped by resource.
Runs6RunTriggers a CI run. Runs can contain one or more workflows.ListRunsReturns CI runs for the authenticated organization, newest first. Filter by status, repository, commit SHA, trigger, or pull request number. Use `pageSize` and `pageToken` to page through additional results.GetRunReturns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use `GetRunStatus`.GetRunStatusReturns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use `GetRun`.GetRunMetricsReturns workflow, job, and attempt CPU and memory metric summaries for one run.CancelRunCancels a queued or running CI run and any of its unfinished workflows, jobs, and attempts. Workflows5ListWorkflowsReturns CI workflows for the authenticated organization, newest first. Filter by name, repository, status, trigger, commit SHA, or pull request number. Use `pageSize` to return up to 200 workflows.GetWorkflowReturns a workflow's identity, status, timestamps, parent run context, execution history, and nested jobs and attempts.DispatchWorkflowTriggers a single workflow configured with an `on.workflow_dispatch` trigger and validates inputs against its input schema.RerunWorkflowResets every job in a workflow that's in a terminal state (finished, failed, or cancelled) to queued and runs them all again. Cancel the workflow first if it's still running.CancelWorkflowCancels a queued or running workflow and all its child jobs. Jobs7GetJobReturns a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, and attempt history.SubmitJobInputSubmit an answer to a running input job.GetJobSummaryReturns authored step summary markdown for a job, a specific attempt, or both.GetJobMetricsReturns per-attempt CPU and memory metric summaries for one job.RetryJobRetries a failed or cancelled job, along with any skipped jobs that depend on it. Fails when a job that depends on it has already started; use `RetryFailedJobs` to retry related failures together.RetryFailedJobsRetries the failed and cancelled jobs in a workflow, along with every job that depends on them. A dependent that already succeeded or was skipped runs again too, because a job it consumed is running again. Queued dependents are left untouched, since they re-check their dependencies before starting. Fails without resetting anything when a waiting or running job depends on the retried set; wait for that job to finish, or cancel the workflow and use `RerunWorkflow`.CancelJobCancels a queued, waiting, or running job and its active attempt. Runs
Create, inspect, measure, and cancel CI runs.
RunCIService.Run
Triggers a CI run. Runs can contain one or more workflows.
Parameters
repostringrequired
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".
shastring | null
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.
workflowstring | null
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.
workflowContentstring[]
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.
jobstring | null
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.
forgeForge
Source-code host containing the repository. Depot Code is supported only for repositories that do not mirror a GitHub repository. Entire requires the Depot plugin installed on the repository's project. Default: FORGE_GITHUB.
Possible enum values
FORGE_UNSPECIFIEDFORGE_GITHUBFORGE_ORIGINFORGE_DEPOT_CODEFORGE_ENTIRE
refstring | null
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.
Returns
orgIdstring
Depot organization that owns this run.
POST/depot.ci.v1.CIService/Run
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/Run \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "repo": "repo_example",8 "sha": "b2f5ff47436671b6e533d8dc3614845d",9 "workflow": "workflow_example",10 "workflowContent": [11 "workflowContent_example"12 ],13 "job": "job_example",14 "forge": "FORGE_UNSPECIFIED",15 "ref": "ref_example"16}17JSON
{ "orgId": "org_123", "runId": "run_123"}
ListRunsCIService.ListRuns
Returns CI runs for the authenticated organization, newest first. Filter by status, repository, commit SHA, trigger, or pull request number. Use pageSize and pageToken to page through additional results.
Parameters
statusstring[]
Statuses of runs to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed. Default: ["running", "queued"].
pageSizeinteger<int32>
Number of runs to return per page. Maximum: 100. Default: 50.
pageTokenstring
Token to fetch the next page of runs. Use the nextPageToken value from a prior response. Leave empty to fetch the first page.
repostring
Repository to return runs from, in owner/name format. For example, "depot/cli". Required if pr is set.
shastring
Commit SHA prefix to return runs for. Matched against the run's sha or headSha. 1-40 hex characters.
triggerstring
Trigger event to return runs for. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
prstring
Pull request number to return runs for. Requires repo.
Returns
runsListRunsResponseRun[]
Recent runs matching the request, newest first.
+Show child parameters
runIdstring
Unique identifier for the CI run.
repostring
GitHub repository in owner/name format. For example, "depot/cli".
triggerstring
Event that triggered the run. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
shastring
Commit SHA the run executes against. Empty for open pull_request runs.
statusstring
Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled".
createdAtstring
Run creation time, in RFC 3339 format.
refstring
Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.
headShastring
Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.
nextPageTokenstring
Token to retrieve the next page of results. Empty when no more pages are available.
POST/depot.ci.v1.CIService/ListRuns
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListRuns \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "status": [8 "status_example"9 ],10 "pageSize": 1,11 "pageToken": "pageToken_example",12 "repo": "repo_example",13 "sha": "b2f5ff47436671b6e533d8dc3614845d",14 "trigger": "trigger_example",15 "pr": "pr_example"16}17JSON
{ "runs": [ { "runId": "run_123", "repo": "repo_example", "trigger": "trigger_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "status": "status_example", "createdAt": "createdAt_example" } ], "nextPageToken": "nextPageToken_example"}
GetRunCIService.GetRun
Returns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use GetRunStatus.
Returns
orgIdstring
Depot organization that owns this run.
runIdstring
Unique identifier for the CI run.
repostring
GitHub repository in owner/name format. For example, "depot/cli".
refstring
Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.
shastring
Commit SHA the run executes against. Empty for open pull_request runs; populated with the merge commit SHA once the PR is closed and merged.
headShastring
Source commit SHA for pull_request and merge_group triggers; matches the PR or merge group head. Empty for triggers that don't carry a head SHA.
triggerstring
Event that triggered the run. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".
statusstring
Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled".
createdAtstring
Creation time, in RFC 3339 format.
startedAtstring
Start time, in RFC 3339 format. Empty until the run starts.
finishedAtstring
Finish time, in RFC 3339 format. Empty until the run finishes.
POST/depot.ci.v1.CIService/GetRun
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRun \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "runId": "run_123"8}9JSON
{ "orgId": "org_123", "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example", "status": "status_example"}
GetRunStatusCIService.GetRunStatus
Returns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use GetRun.
Returns
orgIdstring
Depot organization that owns this run.
runIdstring
Unique identifier for the CI run.
statusstring
Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled".
workflowsWorkflowStatus[]
Workflows in the run with their nested jobs and attempts.
+Show child parameters
workflowIdstring
Unique identifier for the workflow.
statusstring
Current state of the workflow. Can be "queued", "running", "finished", "failed", or "cancelled".
workflowPathstring
Workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.
jobsJobStatus[]
Jobs that make up the workflow.
+Show child parameters
jobIdstring
Unique identifier for the job.
jobKeystring
Job key from the workflow. For example, "build" or "test".
statusstring
Current state of the job. Can be "queued", "waiting", "running", "finished", "failed", "cancelled", or "skipped". "waiting" means the job is blocked behind another run that holds the same concurrency: group slot.
attemptsAttemptStatus[]
All attempts for this job, including the original and any retries. Each contains the attempt's identifier, number, current status, and sandbox/session IDs (when active). Order is not guaranteed.
jobDisplayNamestring
Resolved job name for display. Falls back to the leaf job name, then jobKey, when unavailable. Use jobId or jobKey to identify the job.
namestring
Workflow name from the YAML name: key. Empty when not set.
errorMessagestring
Workflow error or cancellation reason. For example, a compilation or validation error. Empty when the workflow is healthy.
POST/depot.ci.v1.CIService/GetRunStatus
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRunStatus \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "runId": "run_123"8}9JSON
{ "orgId": "org_123", "runId": "run_123", "status": "status_example", "workflows": [ { "workflowId": "workflow_123", "status": "status_example", "workflowPath": "workflowPath_example", "jobs": [ { "jobId": "job_123", "jobKey": "jobKey_example", "status": "status_example", "attempts": [