depot-ci

What this skill does

# Depot CI

Depot CI is a programmable CI system for engineers and agents. Workflows in Depot CI run entirely on Depot compute with built-in job visibility, debuggability, and control. GitHub Actions is the first syntax Depot CI supports: migrate your existing GitHub Actions workflows, and get fast, reliable runs on optimized infrastructure.

## Architecture

Three subsystems: **compute** (provisions and executes work), **orchestrator** (schedules multi-step workflows, handles dependencies), **GitHub Actions parser** (translates Actions YAML into orchestrator workflows). The system is fully programmable.

## Org Context Check for Multi-Org Users

If a user belongs to multiple organizations, before setup/migration or if CI commands can't find expected workflows, verify Depot org context first:

```bash
# Check current org ID
depot org show

# List orgs the user belongs to
depot org list

# Option A: switch default org for this shell/session
depot org switch <org-id>

# Option B: keep current org and target explicitly per command
depot ci run --org <org-id> --workflow .depot/workflows/ci.yml
```

Use `--org <org-id>` when the workflow/repo lives in a different org than the current default.

## Getting Started

### 1. Install the Depot Code Access GitHub App

Depot dashboard → Settings → GitHub Code Access → Connect to GitHub

(If you've used Claude Code on Depot, this may already be installed.)

### 2. Migrate workflows

```bash
depot ci migrate
```

This interactive wizard:

1. Checks that the Depot Code Access app is installed and configured.
1. Discovers all workflows in `.github/workflows/` and analyzes each for Depot CI compatibility.
1. Copies selected workflows to `.depot/workflows/` with inline corrections and comments.
1. Copies local actions from `.github/actions/` to `.depot/actions/`.
1. Detects secrets and variables referenced in workflows and prints next steps for importing them.

Your `.github/` directory is untouched, so workflows run in both GitHub and Depot simultaneously.

**Warning:** Workflows that cause side effects (deploys, artifact updates) will execute twice.

#### Migrate subcommands

The migrate command can also be run as individual steps:

```bash
# Check installation and auth
depot ci migrate preflight

# Copy and transform workflows to .depot/workflows/
depot ci migrate workflows

# Import GitHub Actions secrets and variables into Depot CI
depot ci migrate secrets-and-vars
```

#### Migrate flags

| Flag              | Description                                 |
| ----------------- | ------------------------------------------- |
| `-y, --yes`       | Non-interactive, migrate all workflows      |
| `--overwrite`     | Overwrite existing `.depot/` directory      |
| `--org <id>`      | Organization ID (required if multiple orgs) |
| `--token <token>` | Depot API token                             |

### 3. Import secrets and variables

```bash
depot ci migrate secrets-and-vars
```

This creates and runs a one-shot GitHub Actions workflow on a temporary branch that reads your existing secrets and variables and imports them into Depot CI. The branch is safe to delete afterwards.

You can also add secrets and variables manually with `depot ci secrets add` and `depot ci vars add` (see below).

#### Migrate Secrets-and-Vars flags

| Flag               | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| `-y, --yes`        | Skip preview and confirmation prompts                                              |
| `--branch`         | Override the branch name used for the migration workflow                           |
| `--secrets <name>` | Secret name to include; can be repeated to select multiple. Omit to include all.   |
| `--vars <name>`    | Variable name to include; can be repeated to select multiple. Omit to include all. |
| `--org <id>`       | Organization ID (required if multiple orgs)                                        |
| `--token <token>`  | Depot API token                                                                    |

### 4. Manual setup (without migrate command)

Create `.depot/workflows/` and `.depot/actions/` directories manually. Copy workflow files from `.github/workflows/`. Configure secrets via the CLI.

## Managing Secrets

Secrets can be org-wide or scoped to a specific repository. They can also have **variants**: multiple values for the same name that resolve based on workflow context (repository, branch, workflow file, GitHub environment). The CLI only handles repo scoping; variants with branch, workflow, or environment rules must be created in the dashboard. See the **Secret and Variable Variants** section below for resolution rules.

```bash
# Add (prompts for value securely if --value omitted)
depot ci secrets add SECRET_NAME
depot ci secrets add SECRET_NAME --value "$NPM_TOKEN" --description "NPM auth token"

# Add repo-scoped secret
depot ci secrets add SECRET_NAME --repo owner/repo --value "$NPM_TOKEN"

# List (names and metadata only, no values)
depot ci secrets list
depot ci secrets list --output json
depot ci secrets list --repo owner/repo    # Also show repo-specific secrets

# Remove
depot ci secrets remove SECRET_NAME
depot ci secrets remove SECRET_NAME --force          # Skip confirmation
depot ci secrets remove SECRET_NAME --repo owner/repo  # Remove repo-scoped secret
```

## Credential Safety Guardrails

Treat credentials as sensitive input and never echo them back in outputs.

- For non-interactive flows, pass secret values via environment variables (for example: `--value "$NPM_TOKEN"`), not literals.
- Prefer interactive secret prompts (`depot ci secrets add SECRET_NAME`) over command-line secret values.
- Do not hardcode secrets or tokens in commands, scripts, workflow YAML, logs, or examples.
- Use CI secret stores for `DEPOT_TOKEN` and other credentials; pass at runtime only.
- Avoid force/non-interactive destructive flags unless explicitly requested by the user.
- Before running credential-affecting commands, confirm scope (org, repo, workflow) and intended target.

## Managing Variables

Non-secret config values accessible as `${{ vars.VARIABLE_NAME }}`. Unlike secrets, values can be read back. Variables can be org-wide or scoped to a specific repository, just like secrets.

```bash
# Add org-wide variable
depot ci vars add VAR_NAME --value "some-value"

# Add repo-scoped variable
depot ci vars add VAR_NAME --value "some-value" --repo owner/repo

# List
depot ci vars list
depot ci vars list --output json
depot ci vars list --repo owner/repo    # Also show repo-specific variables

# Remove
depot ci vars remove VAR_NAME
depot ci vars remove VAR_NAME --force
depot ci vars remove VAR_NAME --repo owner/repo
```

## Secret and Variable Variants

A variant is another secret or variable with the same name but different repository scope or access rules. Variants let one name resolve to different values depending on the workflow context, for example a different `DATABASE_URL` for `production` vs `staging`, or for one repo vs all repos.

Variants are created and managed in the dashboard ([Depot CI workflows](https://depot.dev/orgs/_/workflows) → Settings → Secrets/Variables → Add variant). The CLI only supports repository scoping, so anything beyond that requires the dashboard.

### Access rule kinds

Limit when a variant is selected by combining one or more rules:

- **Repository**: select when the workflow runs in a specific repository.
- **Branch**: select when the branch name matches; supports glob patterns like `release/*`.
- **Workflow**: select when the workflow file matches; supports glob patterns like `deploy-*.yaml`.
- **Environment**: select when the job's GitHub `environment` field matches exactly. Provides compatibility with GitHub Environment Secrets. Jobs without an `environment` field never match environment rules.

Within a