depot-ci

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Depot CI是GitHub Actions的即插即用替代方案，可在Depot的基础设施内完整运行您现有的Actions格式YAML工作流。它会解析GitHub Actions工作流文件，并在Depot的计算资源上执行。

状态：Beta版 — 请保持GitHub Actions并行运行。可能会出现问题。

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.

包含三个子系统：计算层（提供并执行工作任务）、编排器（调度多步骤工作流、处理依赖关系）、GitHub Actions解析器（将Actions YAML转换为编排器可执行的工作流）。该系统完全可编程——计划提供对工作流、编排和计算沙箱的直接API访问。

Getting Started

快速开始

1. Install the Depot Code Access GitHub App

1. 安装Depot Code Access GitHub应用

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

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

登录Depot控制台 → 设置 → GitHub代码访问 → 连接到GitHub

（如果您已经在Depot上使用过Claude Code，该应用可能已安装。）

2. Migrate workflows

2. 迁移工作流

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.

bash

depot ci migrate

这个交互式向导会：

发现
```
.github/workflows/
```
目录下的所有工作流
分析每个工作流与Depot CI的兼容性
将选中的工作流复制到
```
.depot/workflows/
```
目录
将本地动作从
```
.github/actions/
```
复制到
```
.depot/actions/
```
目录
提示输入工作流中引用的密钥和变量

您的

.github/

目录不会被修改——工作流会同时在GitHub和Depot上运行。

警告： 会产生副作用的工作流（如部署、更新制品）将执行两次。

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

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

参数	描述
`--yes`	非交互式模式，迁移所有工作流
`--secret KEY=VALUE`	预先提供密钥（可重复使用）
`--var KEY=VALUE`	预先提供变量（可重复使用）
`--overwrite`	覆盖现有的 `.depot/` 目录
`--org <id>`	组织ID（当存在多个组织时为必填项）
`--token <token>`	Depot API令牌

3. Manual setup (without migrate command)

3. 手动设置（不使用migrate命令）

Create

.depot/workflows/

and

.depot/actions/

directories manually. Copy workflow files from

.github/workflows/

. Configure secrets via CLI or API.

手动创建

.depot/workflows/

和

.depot/actions/

目录。将工作流文件从

.github/workflows/

复制过来。通过CLI或API配置密钥。

Managing Secrets

管理密钥

bash

undefined

bash

undefined

Add (prompts for value securely if --value omitted)

添加密钥（如果省略--value则安全地提示输入值）

depot ci secrets add SECRET_NAME depot ci secrets add SECRET_NAME --value "my-secret-value" --description "NPM auth token"

depot ci secrets add SECRET_NAME depot ci secrets add SECRET_NAME --value "my-secret-value" --description "NPM认证令牌"

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

undefined

depot ci secrets remove SECRET_NAME depot ci secrets remove SECRET_NAME --force # 跳过确认

undefined

Secrets via API

通过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..."}'

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"}]}'

undefined

undefined

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

非保密的配置值，可通过

${{ vars.VARIABLE_NAME }}

访问。与密钥不同，变量值可以被读取。

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

undefined

bash

undefined

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)

通过SSH调试（在第N步后启动tmate会话，需指定单个--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.

depot ci run --workflow .depot/workflows/ci.yml --job build --ssh-after-step 3


CLI会自动检测未提交的更改与默认分支的差异，将补丁上传到Depot缓存，并注入一个步骤在检出后应用补丁——无需推送即可运行本地工作状态。

Checking Status and Logs

检查状态和日志

bash

undefined

bash

undefined

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>

undefined

depot ci logs <attempt-id>

undefined

Compatibility with GitHub Actions

与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

工作流层面：

name

、

run-name

、

on

、

env

、

defaults

、

jobs

、

on.workflow_call

（包含输入、输出、密钥）

触发器：

push

（分支、标签、路径）、

pull_request

（分支、路径）、

pull_request_target

、

schedule

、

workflow_call

、

workflow_dispatch

（包含输入）、

workflow_run

任务层面：

name

、

needs

、

if

、

outputs

、

env

、

defaults

、

timeout-minutes

、

strategy

（矩阵、快速失败、最大并行数）、

continue-on-error

、

container

、

services

、

uses

（可复用工作流）、

with

、

secrets

、

secrets.inherit

、

steps

步骤层面：

id

、

name

、

if

、

uses

、

run

、

shell

、

with

、

env

、

working-directory

、

continue-on-error

、

timeout-minutes

表达式：

github

、

env

、

vars

、

secrets

、

needs

、

strategy

、

matrix

、

steps

、

job

、

runner

、

inputs

上下文。函数：

always()

、

success()

、

failure()

、

cancelled()

、

contains()

、

startsWith()

、

endsWith()

、

format()

、

join()

、

toJSON()

、

fromJSON()

动作类型： JavaScript（Node 12/16/20/24）、复合动作、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)

concurrency

（工作流和任务层面）、

hashFiles()

、

permissions

（部分支持——

actions

、

checks

、

contents

、

metadata

、

pull_requests

、

statuses

、

workflows

可用；

id-token

需要OIDC，目前尚未支持）

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

跨仓库可复用工作流 —— 本地可复用工作流可用；跨仓库
```
uses
```
不支持
分支触发的PR —— 暂不支持来自分支的
```
pull_request
```
和
```
pull_request_target
```
非Ubuntu运行器标签 —— 所有非Depot标签都被视为
```
depot-ubuntu-latest
```
OIDC —— 暂不支持
```
id-token
```
权限
并发组 —— 尚未实现
层级化密钥/变量 —— 仅支持组织范围，无法按仓库区分
自定义运行器快照 —— Depot自有实现正在规划中
许多GitHub特定事件触发器 ——
```
release
```
、
```
issues
```
、
```
issue_comment
```
、
```
deployment
```
、
```
create
```
、
```
delete
```
、
```
merge_group
```
等

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

Depot CI支持Depot运行器标签（如

depot-ubuntu-24.04-8

）。任何无法解析的标签都会被视为

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

your-repo/
├── .github/
│   ├── workflows/     # 原始GHA工作流（保持运行）
│   └── actions/       # 本地复合动作
├── .depot/
│   ├── workflows/     # Depot CI工作流副本
│   └── actions/       # Depot CI本地动作副本

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

错误	修复方案
迁移后删除 `.github/workflows/` 目录	保留该目录——Beta阶段请保持两者并行运行
使用跨仓库可复用工作流	暂不支持——将工作流内联或本地复制
期望OIDC正常工作	暂不支持——使用 `DEPOT_TOKEN` 进行认证
设置仓库级别的密钥	密钥仅支持组织范围——所有仓库使用相同值
多组织场景下忘记 `--org` 参数	迁移会失败——请始终指定 `--org <id>`
工作流使用 `runs-on: windows-latest`	会被视为 `depot-ubuntu-latest` ——可能执行失败