Depot CI (Beta)

Depot CI is a drop-in replacement for GitHub Actions that runs your existing Actions-format YAML workflows entirely within Depot's infrastructure. It parses GitHub Actions workflow files and executes them on Depot's compute.

Status: Beta — keep GitHub Actions running in parallel. Things may break.

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 — direct API access to workflows, orchestration, and compute sandboxes is planned.

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:

Discovers all workflows in
```
.github/workflows/
```
Analyzes each for Depot CI compatibility
Copies selected workflows to
```
.depot/workflows/
```
Copies local actions from
```
.github/actions/
```
to
```
.depot/actions/
```
Prompts for secrets and variables referenced in workflows

Your

.github/

directory is untouched — workflows run in both GitHub and Depot simultaneously.

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

Non-interactive migration

bash

depot ci migrate --yes \
  --secret NPM_TOKEN=npm_abc123 \
  --secret DATABASE_URL=postgres://... \
  --var SERVICE_NAME=api \
  --org my-org-id

Migrate flags

Flag	Description
`--yes`	Non-interactive, migrate all workflows
`--secret KEY=VALUE`	Pre-supply secret (repeatable)
`--var KEY=VALUE`	Pre-supply variable (repeatable)
`--overwrite`	Overwrite existing `.depot/` directory
`--org <id>`	Organization ID (required if multiple orgs)
`--token <token>`	Depot API token

3. Manual setup (without migrate command)

Create

.depot/workflows/

and

.depot/actions/

directories manually. Copy workflow files from

.github/workflows/

. Configure secrets via CLI or API.

Managing Secrets

bash

# Add (prompts for value securely if --value omitted)
depot ci secrets add SECRET_NAME
depot ci secrets add SECRET_NAME --value "my-secret-value" --description "NPM auth token"

# List (names and metadata only, no values)
depot ci secrets list
depot ci secrets list --output json

# Remove
depot ci secrets remove SECRET_NAME
depot ci secrets remove SECRET_NAME --force  # Skip confirmation

Secrets via API

bash

curl -X POST https://api.depot.dev/depot.ci.v1.SecretService/AddSecret \
  -H "Authorization: Bearer ${DEPOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "NPM_TOKEN", "value": "npm_abc123..."}'

# Batch add
curl -X POST https://api.depot.dev/depot.ci.v1.SecretService/BatchAddSecrets \
  -H "Authorization: Bearer ${DEPOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"secrets": [{"name": "NPM_TOKEN", "value": "npm_abc123..."}, {"name": "DB_PASS", "value": "secret"}]}'

Managing Variables

Non-secret config values accessible as

${{ vars.VARIABLE_NAME }}

. Unlike secrets, values can be read back.

bash

depot ci vars add VAR_NAME --value "some-value"
depot ci vars list
depot ci vars list --output json
depot ci vars remove VAR_NAME
depot ci vars remove VAR_NAME --force

Running Workflows

bash

# Run a workflow
depot ci run --workflow .depot/workflows/ci.yml

# Run specific jobs only
depot ci run --workflow .depot/workflows/ci.yml --job build --job test

# Debug with SSH (tmate session after step N, requires single --job)
depot ci run --workflow .depot/workflows/ci.yml --job build --ssh-after-step 3

The CLI auto-detects uncommitted changes vs. the default branch, uploads a patch to Depot Cache, and injects a step to apply it after checkout — your local working state runs without needing a push.

Checking Status and Logs

bash

# Check run status (shows workflows → jobs → attempts hierarchy)
depot ci status <run-id>

# Fetch logs for a specific job attempt
depot ci logs <attempt-id>

Compatibility with GitHub Actions

Supported

Workflow level:

name

run-name

on

env

defaults

jobs

on.workflow_call

(with inputs, outputs, secrets)

Triggers:

push

(branches, tags, paths),

pull_request

(branches, paths),

pull_request_target

schedule

workflow_call

workflow_dispatch

(with inputs),

workflow_run

Job level:

name

needs

if

outputs

env

defaults

timeout-minutes

strategy

(matrix, fail-fast, max-parallel),

continue-on-error

container

services

uses

(reusable workflows),

with

secrets

secrets.inherit

steps

Step level:

id

name

if

uses

run

shell

with

env

working-directory

continue-on-error

timeout-minutes

Expressions:

github

env

vars

secrets

needs

strategy

matrix

steps

job

runner

inputs

contexts. Functions:

always()

success()

failure()

cancelled()

contains()

startsWith()

endsWith()

format()

join()

toJSON()

fromJSON()

Action types: JavaScript (Node 12/16/20/24), Composite, Docker

In Progress

concurrency

(workflow and job level),

hashFiles()

permissions

(partially supported —

actions

checks

contents

metadata

pull_requests

statuses

workflows

work;

id-token

requires OIDC which is not yet supported)

Not Supported

Reusable workflows from other repositories — local reusable workflows work; cross-repo
```
uses
```
does not
Fork-triggered PRs —
```
pull_request
```
and
```
pull_request_target
```
from forks not supported yet
Non-Ubuntu runner labels — all non-Depot labels treated as
```
depot-ubuntu-latest
```
OIDC —
```
id-token
```
permission not available yet
Concurrency groups — not yet implemented
Hierarchical secrets/variables — scoped to org only, cannot vary per-repository
Custom runner snapshots — Depot's own implementation planned

Many GitHub-specific event triggers —

release

issues

issue_comment

deployment

create

delete

merge_group

, and others

Runner label handling

Depot CI respects Depot runner labels (e.g.,

depot-ubuntu-24.04-8

). Any label it can't parse is treated as

depot-ubuntu-latest

Directory Structure

your-repo/
├── .github/
│   ├── workflows/     # Original GHA workflows (keep running)
│   └── actions/       # Local composite actions
├── .depot/
│   ├── workflows/     # Depot CI copies of workflows
│   └── actions/       # Depot CI copies of local actions

Common Mistakes

Mistake	Fix
Removing `.github/workflows/` after migration	Keep them — run both in parallel during beta
Using cross-repo reusable workflows	Not supported yet — inline the workflow or copy it locally
Expecting OIDC to work	Not supported yet — use `DEPOT_TOKEN` for auth
Setting per-repo secrets	Secrets are org-scoped only — same value across all repos
Forgetting `--org` flag with multiple orgs	Migration will fail — always specify `--org <id>`
Workflows with `runs-on: windows-latest`	Treated as `depot-ubuntu-latest` — may fail

depot-ci

NPX Install

Tags

SKILL.md Content

Depot CI (Beta)

Architecture

Getting Started

1. Install the Depot Code Access GitHub App

2. Migrate workflows

Non-interactive migration

Migrate flags

3. Manual setup (without migrate command)

Managing Secrets

Secrets via API

Managing Variables

Running Workflows

Checking Status and Logs

Compatibility with GitHub Actions

Supported

In Progress

Not Supported

Runner label handling

Directory Structure

Common Mistakes