---
title: "overlane ci run"
description: "Start a pipeline run for a commit"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# overlane ci run

{/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */}

Starts the pipeline from .overlane/ci.yml at a commit (default: the working copy's HEAD and branch). The file is read from the repository, never sent. A failed run exits 1; a run held by the pull request's cost gate exits 6 and names the setting to raise. A native project needs a repository (`overlane repo create`).

## Usage

```sh
overlane ci run [--commit SHA] [--ref BRANCH] [--repo REPO] [--pull N] [--approval ID] [--dry-run]
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--commit` | string | no |  | The full commit SHA (default: HEAD) |
| `--ref` | string | no |  | The branch (default: the current branch) |
| `--repo` | string | no |  | The repository, when the project has several |
| `--pull` | string | no |  | Run as the pull request with this number (its head must be the commit) |
| `--approval` | string | no |  | Run an action that an approval covers; get the ID from `overlane guard approvals list` |
| `--dry-run` | boolean | no |  | Print the requests and file changes this command would make, then stop. Needs no credentials. |

## Examples

```sh
overlane ci run
overlane ci run --commit 0123456789abcdef0123456789abcdef01234567 --ref main --dry-run
```

## Behavior

- Effect: `write` (changes local or hosted state).
- Needs credentials: yes. Uses the network: yes.
- Supports `--dry-run`: yes. Accepts `--force`: no.
- Machine-readable description: `overlane schema ci run`.

## Result

With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout.

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "tenantId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
          "description": "tenant identifier"
        },
        "run": {
          "type": "object",
          "properties": {
            "schemaVersion": {
              "type": "string",
              "const": "1"
            },
            "tenantId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
              "description": "tenant identifier"
            },
            "projectId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
              "description": "project identifier"
            },
            "runId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "provider": {
              "type": "string",
              "enum": [
                "overlane",
                "github",
                "gitlab"
              ]
            },
            "repoId": {
              "type": [
                "string",
                "null"
              ]
            },
            "repository": {
              "type": [
                "string",
                "null"
              ]
            },
            "commitSha": {
              "type": "string",
              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
            },
            "ref": {
              "type": "string",
              "maxLength": 200
            },
            "trigger": {
              "type": "string",
              "enum": [
                "push",
                "pull_request",
                "schedule",
                "manual"
              ]
            },
            "pullNumber": {
              "anyOf": [
                {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            },
            "fork": {
              "type": "boolean"
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "passed",
                "failed",
                "cancelled",
                "held"
              ]
            },
            "reason": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 300
                },
                {
                  "type": "null"
                }
              ]
            },
            "supersededBy": {
              "type": [
                "string",
                "null"
              ]
            },
            "configDigest": {
              "type": "string",
              "pattern": "^sha256:[0-9a-f]{64}$"
            },
            "jobs": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "tenantId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
                    "description": "tenant identifier"
                  },
                  "jobId": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "queued",
                      "running",
                      "passed",
                      "failed",
                      "cancelled",
                      "held"
                    ]
                  },
                  "route": {
                    "type": "object",
                    "properties": {
                      "target": {
                        "type": "string",
                        "const": "containers"
                      },
                      "instance": {
                        "type": "string",
                        "enum": [
                          "standard-3",
                          "standard-4"
                        ]
                      },
                      "reason": {
                        "type": "string",
                        "maxLength": 300
                      },
                      "database": {
                        "type": "object",
                        "properties": {
                          "engine": {
                            "type": "string",
                            "enum": [
                              "postgres",
                              "sqlite"
                            ]
                          },
                          "runtime": {
                            "type": "string",
                            "enum": [
                              "durable-object-sqlite",
                              "pglite",
                              "external",
                              "container"
                            ]
                          },
                          "sizeMb": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "exclusiveMinimum": 0,
                                "maximum": 9007199254740991
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "reason": {
                            "type": "string",
                            "maxLength": 500
                          }
                        },
                        "required": [
                          "engine",
                          "runtime",
                          "sizeMb",
                          "reason"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "target",
                      "instance",
                      "reason"
                    ],
                    "additionalProperties": false
                  },
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "exitCode": {
                          "type": "integer",
                          "minimum": -9007199254740991,
                          "maximum": 9007199254740991
                        },
                        "durationMs": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "attempt": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 2
                        },
                        "skipped": {
                          "default": false,
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "name",
                        "exitCode",
                        "durationMs",
                        "attempt",
                        "skipped"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "cache": {
                    "type": "object",
                    "properties": {
                      "key": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "hit": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "key",
                      "hit"
                    ],
                    "additionalProperties": false
                  },
                  "flaky": {
                    "type": "boolean"
                  },
                  "logUri": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "logDigest": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^sha256:[0-9a-f]{64}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "durationMs": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "billedMinutes": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "costMicros": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "startedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "finishedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "tenantId",
                  "jobId",
                  "name",
                  "status",
                  "route",
                  "steps",
                  "cache",
                  "flaky",
                  "logUri",
                  "logDigest",
                  "durationMs",
                  "billedMinutes",
                  "costMicros",
                  "startedAt",
                  "finishedAt"
                ],
                "additionalProperties": false
              }
            },
            "totalMinutes": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "totalCostMicros": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "finishedAt": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "schemaVersion",
            "tenantId",
            "projectId",
            "runId",
            "provider",
            "repoId",
            "repository",
            "commitSha",
            "ref",
            "trigger",
            "pullNumber",
            "fork",
            "status",
            "reason",
            "supersededBy",
            "configDigest",
            "jobs",
            "totalMinutes",
            "totalCostMicros",
            "createdAt",
            "finishedAt"
          ],
          "additionalProperties": false
        },
        "replay": {
          "type": "boolean"
        },
        "cancelled": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "tenantId",
        "run",
        "replay",
        "cancelled"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "dryRun": {
          "type": "boolean",
          "const": true
        },
        "service": {
          "type": "string"
        },
        "requests": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "method": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "body": {},
              "note": {
                "type": "string"
              }
            },
            "required": [
              "method",
              "path"
            ],
            "additionalProperties": false
          }
        },
        "commands": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "writes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": [
                  "write",
                  "append",
                  "delete"
                ]
              },
              "description": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "action",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "dryRun",
        "requests",
        "commands",
        "writes",
        "notes"
      ],
      "additionalProperties": false
    }
  ]
}
```

See [exit codes](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/ci-run/index.mdx