depot-ci

Depot CI

Depot CI 是面向工程师和 Agent 的可编程 CI 系统。Depot CI 中的工作流完全在 Depot 计算资源上运行，并内置作业可见性、可调试性和控制能力。GitHub Actions 是 Depot CI 首先支持的语法：迁移现有的 GitHub Actions 工作流，即可在经过优化的基础设施上快速、可靠地运行。

此 SKILL.md 涵盖核心工作流和最常用的命令。详细的标志表、JSON 输出格式以及较少使用的命令，位于 references/ 下的相关文件中，下面各节会提供相应链接。只有在需要其中的详细信息时，才加载相应的参考文件。

架构

包含三个子系统：计算（配置并执行工作）、编排器（安排多步骤工作流并处理依赖关系）、GitHub Actions 解析器（将 Actions YAML 转换为编排器工作流）。整个系统完全可编程。

常用标志

几乎所有 depot ci 命令（以及 depot tests）都接受：

• --org <id>：组织 ID；当用户属于多个组织时为必填项（请参阅下文的组织上下文检查）。
• --token <token>：Depot API 令牌。
• -o, --output json：输出机器可读格式，便于 Agent 和脚本使用。大多数 depot ci 子命令都接受简写 -o，但 depot tests、depot ci secrets 和 depot ci vars 只接受完整形式 --output。

参考文件中的命令表省略了这些标志以减少冗余；请默认它们均可使用。

多组织用户的组织上下文检查

如果用户属于多个组织，请在设置或迁移之前，或者 CI 命令无法找到预期工作流时，先确认 Depot 组织上下文：

depot org show              # Current org ID
depot org list              # Orgs the user belongs to
depot org switch <org-id>   # Option A: switch default org for this shell/session

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

如果工作流或仓库位于当前默认组织之外，请使用 --org <org-id>。

开始使用

1. 安装 Depot Code Access GitHub App

Depot 控制面板 → Settings → GitHub Code Access → Connect to GitHub。（如果你曾在 Depot 上使用 Claude Code，该应用可能已经安装。）

2. 迁移工作流

depot ci migrate

此交互式向导会：

1. 检查 Depot Code Access 应用是否已安装并配置。
2. 查找 .github/workflows/ 中的所有工作流，并分析每个工作流与 Depot CI 的兼容性。
3. 将选定的工作流复制到 .depot/workflows/，并附上内联修正和注释；同时将本地操作从 .github/actions/ 复制到 .depot/actions/。
4. 检测工作流中引用的密钥和变量，并打印导入所需的后续步骤。

.github/ 目录不会被修改，因此工作流会同时在 GitHub 和 Depot 中运行。警告： 会产生副作用的工作流（例如部署、更新构件）将执行两次。

3. 导入密钥和变量

depot ci migrate secrets-and-vars

此操作会在临时分支上创建并运行一次性 GitHub Actions 工作流，读取现有密钥和变量并将其导入 Depot CI。你也可以使用 depot ci secrets add / depot ci vars add 手动添加（请参阅下文的管理密钥和变量）。

迁移详情（preflight/workflows/secrets-and-vars 子命令、对应的标志表、具体的转换内容以及手动设置方法），请阅读 references/migration.md。

管理机密和变量

机密（引用方式为 ${{ secrets.NAME }}，经过加密，创建后无法读取）和变量（引用方式为 ${{ vars.NAME }}，值可读取）共用变体模型。一个名称可包含一个或多个变体；每个变体都包含一个值，以及可选的选择器（--repo、--env、--branch、--workflow），用于按仓库、GitHub 环境、分支和工作流文件匹配作业。不带任何选择器的变体适用于组织中的所有作业。CLI 可直接管理所有四种选择器，因此变体不再需要通过控制面板管理。

机密值可通过交互式提示、管道传入的 stdin，或 KEY=VALUE 批量键值对提供（机密不支持 --value 标志）。变量值可通过 --value、提示或 KEY=VALUE 键值对提供。

# Secrets: add (prompt or piped stdin), list, remove
depot ci secrets add SECRET_NAME                                   # Prompts securely
printf '%s' "$NPM_TOKEN" | depot ci secrets add SECRET_NAME        # From stdin (scripts)
depot ci secrets add SECRET_NAME --repo owner/repo --branch main   # Scoped variant
depot ci secrets list
depot ci secrets remove SECRET_NAME

# Variables: add, list, remove
depot ci vars add VAR_NAME --value "some-value"
depot ci vars add VAR_NAME --value "prod" --repo owner/repo --env production   # Scoped variant
depot ci vars list
depot ci vars remove VAR_NAME

完整的命令说明（set、bulk 和 get secrets 子命令、所有标志表，以及 Depot 在运行时如何确定哪个变体生效），请参阅 references/secrets-and-variables.md。

凭据安全

请将凭据视为敏感输入，绝不要在输出中回显。

• 对于非交互式流程，请通过 stdin 管道传入机密值（例如，printf '%s' "$NPM_TOKEN" | depot ci secrets set SECRET_NAME --from-stdin），不要在命令行中直接输入字面值。
• 优先使用交互式提示，不要将机密值作为命令参数传递。不要在命令、脚本、工作流 YAML、日志或示例中硬编码机密或令牌。
• 在外部 CI 系统中，运行时应从 CI 机密存储传入 Depot 凭据。Depot CI 保留 DEPOT_TOKEN，并会为受信任作业中的构建注入作业令牌。不要创建名为 DEPOT_TOKEN 的 Depot CI 机密。
• 除非收到明确请求，否则避免使用强制或非交互式的破坏性标志。运行会影响凭据的命令前，请确认作用范围（组织、仓库、工作流）和目标。

运行工作流

# Run a workflow (auto-detects repo from git remotes, applies local uncommitted changes)
depot ci run --workflow .depot/workflows/ci.yml

# Run in a specific org (for multi-org users)
depot ci run --org <org-id> --workflow .depot/workflows/ci.yml

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

# Trigger a run and stream its logs live
depot ci run --workflow .depot/workflows/ci.yml --job test --follow

# Run a job and connect via SSH
depot ci run --workflow .depot/workflows/ci.yml --job build --ssh

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

# Override the auto-detected repository (multiple remotes or no origin)
depot ci run --workflow .depot/workflows/ci.yml --repo owner/repo

# Select Depot Code explicitly for a mirrored repository
depot ci run --workflow .depot/workflows/ci.yml --forge depot

CLI 会根据 git 远程仓库检测 GitHub、Origin 和 Depot Code。只有所有受支持的远程仓库都使用 Depot Code 时，Depot Code 才会自动启用；镜像检出默认使用 GitHub 或 Origin。设置 --forge 为 github、origin 或 depot 以选择代码托管平台。使用 --repo <name> 选择仓库。如果没有匹配的远程仓库，则为相应代码托管平台指定 --forge origin 或 --forge depot。

本地补丁包含相对于分支远程状态尚未推送的更改；对于仅存在于本地的分支，则包含相对于默认分支的更改。CLI 会将补丁上传到 Depot Cache，并在 actions/checkout 后注入一个应用步骤。调用可复用工作流的作业没有用于注入补丁的步骤，因此会运行不含本地更改的合并基准代码；CLI 会发出警告。

启动新运行时，使用 --ssh / --ssh-after-step 开启调试会话；两者都要求恰好指定一个 --job，且不能同时使用。使用 depot ci ssh 连接正在运行的作业。传入 --follow 可实时输出触发运行的日志：它会跟踪单个指定作业；若有多个作业正在运行，则会选择唯一作业，或提示你进行选择。--follow 不能与 --ssh / --ssh-after-step 同时使用。

分派工作流

depot ci dispatch 可在终端中通过 workflow_dispatch 触发工作流。输入会根据工作流声明的输入架构进行验证（必须输入的字段必须提供，带类型的输入会进行类型转换）。

depot ci dispatch --repo depot/cli --workflow deploy.yml --ref main
depot ci dispatch --repo depot/cli --workflow deploy.yml --ref main \
  --input environment=staging --input dry_run=true
depot ci dispatch --repo depot/cli --workflow deploy.yml --ref main --output json

--workflow 接受工作流文件的基本名称（例如 deploy.yml），而不是完整路径 .depot/workflows/deploy.yml，这与 GitHub 的 workflow_dispatch API 约定一致。必需的标志：--repo <owner/repo>、--workflow <filename>、--ref <branch-or-tag>。--input <key>=<value> 可重复使用。

depot.actor 上下文用于标识创建运行的人；depot.triggering_actor 用于标识启动当前尝试的人，包括重试和重新运行。两者都公开 kind、id、email 和 name。Actor 类型包括 user、organization_token、service 和 github；只有用户才有电子邮件地址。对应的环境变量为 DEPOT_ACTOR_KIND、DEPOT_ACTOR_ID、DEPOT_ACTOR_EMAIL、DEPOT_ACTOR_NAME、DEPOT_TRIGGERING_ACTOR_KIND、DEPOT_TRIGGERING_ACTOR_ID、DEPOT_TRIGGERING_ACTOR_EMAIL 和 DEPOT_TRIGGERING_ACTOR_NAME。GitHub Actor 上下文保留其 GitHub 语义。

自定义镜像

构建一次自定义镜像，并在多个作业中重复使用，以跳过重复的设置步骤。自定义镜像是 Depot CI 沙箱的快照，存储在组织的 Depot 注册表中，任何工作流中的任何作业都可以通过名称引用。

构建镜像

在运行设置步骤的作业中添加 snapshot: 关键字。步骤完成后，Depot 会捕获沙箱状态，并将其推送到 Depot 注册表，作为可重复使用的镜像。快照作业会先检查请求的标签是否已存在：如果存在，Depot 会跳过该作业并重复使用快照；如果不存在，Depot 会运行该作业并创建快照。

jobs:
  build-image:
    runs-on: depot-ubuntu-latest
    snapshot: ci-base:v1
    steps:
      - run: sudo apt-get update && sudo apt-get install -y your-tool

如需高级配置，请使用展开形式的 snapshot:。with: 块用于配置底层的 depot/snapshot-action；例如，max-age 会在达到指定时长后强制重建：

jobs:
  build-image:
    runs-on: depot-ubuntu-latest
    snapshot:
      image-name: ci-base
      version: v1
      with:
        max-age: 5d
    steps:
      - run: sudo apt-get update && sudo apt-get install -y your-tool

如果未指定版本，Depot 会使用 latest 标签。指定版本（例如 v1）时，快照会同时标记为 v1 和 latest，因此使用者可以固定到某个版本，也可以跟随 latest。

使用镜像

在任何 Depot CI 作业中，通过 runs-on 对象语法引用镜像，并指定 size 和 image（两者均为必填项）：

jobs:
  test:
    runs-on:
      size: 2x8
      image: ci-base
    steps:
      - uses: actions/checkout@v4

image 的值可以是 ci-base 这样的简写名称（Depot 会将其展开为 {orgId}.registry.depot.dev/depot/snapshots/ci-base），也可以是完整的 Depot Registry 引用 {orgId}.registry.depot.dev/some-image。它必须引用由快照作业创建的镜像，而不能是任意镜像。

可用规格：2x8、4x16、8x32、16x64、32x128、64x256（CPU 数量 x RAM，单位为 GB）。

**限制：**镜像会推送到 Depot 注册表，并且必须从 Depot 注册表（registry.depot.dev）拉取；不支持外部注册表。

并行步骤

Depot CI 支持在单个作业中使用 parallel: 块并发运行步骤，从而将作业时长缩短至最慢分支所需的时间，而不是所有步骤耗时的总和。这是 Depot CI 专属功能，与 GitHub Actions 运行器不兼容。

在 steps: 中使用 parallel:，其中可包含单独的步骤或 sequential: 分组。每个分支都从相同的作业状态开始；所有分支的步骤输出、环境变量和 $GITHUB_PATH 更改都会在块完成时合并。

# Run lint, typecheck, and tests concurrently
steps:
  - uses: actions/checkout@v4
  - name: Install dependencies
    run: pnpm install
  - parallel:
      - name: Lint
        run: pnpm lint
      - name: Typecheck
        run: pnpm type-check
      - name: Test
        run: pnpm test

在 parallel: 中使用 sequential:，将必须在一个分支内按顺序运行的步骤分组：

- parallel:
    - sequential:
        - name: Build
          run: npm run build
        - name: Test
          run: npm test
    - name: Lint
      run: npm run lint

使用 fail-fast: 控制失败行为。默认值为 true（取消块中其余步骤）；设为 false 则会让所有步骤运行至完成：

- fail-fast: false
  parallel:
    - name: Lint
      run: pnpm lint
    - name: Typecheck
      run: pnpm type-check

在 parallel: 块中的单个步骤上设置 continue-on-error: true，可忽略该步骤的失败，使整个组仍有可能成功。这与 fail-fast: 不同：后者只控制发生失败时是否取消其余步骤，并不决定整个组是否失败：

- parallel:
    - name: Optional check
      continue-on-error: true
      run: pnpm optional-check
    - name: Required check
      run: pnpm required-check

限制：

• 不能在另一个 parallel: 中嵌套 parallel:（请改为在 parallel: 中使用 sequential:）。
• id 步骤值在整个作业中必须唯一（包括不同的并行块）。

重试步骤

通过添加 retry: 键，自动重新运行失败的 run: 步骤，以应对不稳定命令（网络短暂中断、注册表临时错误）。Depot 会在退避延迟后就地重新运行该步骤；如果后续尝试成功，作业便会继续。任何非零退出都会触发重试（不按退出代码筛选），且仅支持 run: 步骤；在解析时会拒绝对 uses: 操作步骤使用 retry:，因为操作包含 post: 和状态机制，重新运行并不安全。

简写形式用于设置额外尝试次数：

steps:
  - run: npm ci
    retry: 3   # up to 4 total runs

结构化形式用于控制退避策略和延迟：

steps:
  - run: ./flaky-integration-test.sh
    retry:
      retries: 3            # additional attempts after the first run (1-10)
      backoff: exponential  # 'constant' (default) or 'exponential'
      delay-seconds: 5      # base delay before the first retry (default 5)
      max-delay-seconds: 60 # cap on a single delay (default 60)

retries: N 表示最多总共运行 N + 1 次。constant 会在每次重试前等待 delay-seconds；exponential 会在每次尝试时将等待时间加倍（第 n 次尝试等待 delay-seconds × 2^(n-1)），直至达到 max-delay-seconds。timeout-minutes 按每次尝试生效（每次都会获得新的时间预算），而 continue-on-error 仅会在所有重试用尽后应用。尝试之间不会重置状态，因为重试会复用同一沙盒；因此，如果某个步骤需要干净的初始状态，请先自行添加清理操作。

沙盒功能

• 嵌套虚拟化：每个 Depot CI 沙盒都会提供 /dev/kvm，并默认启用硬件虚拟化，因此 KVM/QEMU、Android 模拟器和基于 VM 的端到端测试无需额外配置即可运行。
• DEPOT_JOB_URL：每个作业的环境中都包含 DEPOT_JOB_URL，这是 Depot 控制面板中该作业的直接链接。
• GitHub 检查：Depot CI 会为工作流运行中的每个作业自动报告一项 GitHub 检查。

如果 GitHub API 限流导致检查更新延迟，组织所有者可以在 Settings → Connections → GitHub Checks 下连接 Depot Checks 和 Depot Checks 2。必须先连接 Depot Code Access。请允许检查应用访问相同的仓库。如果已批准的连接仍处于待处理状态，请使用 Finish connecting。

添加检查应用之前，请将所需的 Depot 检查来源设置为 Any source，因为多个应用可能会发布同名检查。Any source 也允许其他仓库写入者满足该名称。如果需要特定应用的信任，请保留固定来源，并跳过其他应用。现有检查仍归属其原始应用，仍可能受到该应用的限流影响。

用于云身份验证的 OIDC

Depot CI 会为每个任务颁发签名 JWT，让工作流使用短期令牌向云服务商（AWS、GCP、Azure）进行身份验证，而不是使用静态凭据。请在工作流中设置 permissions: id-token: write，以颁发令牌；颁发者为 https://identity.depot.dev。Depot 会将令牌请求凭据注入环境，因此无需额外配置即可使用 aws-actions/configure-aws-credentials 等标准操作。

有关服务商信任策略的设置、sub spiffe 声明格式和通配符、完整的令牌声明参考，以及迁移现有 GitHub Actions OIDC 信任策略，请阅读 references/oidc.md。

Datadog CI 可见性

在 Depot 组织设置中启用 Datadog CI 可见性，然后添加名为 DD_API_KEY 的 Depot CI 密钥。如果 Datadog 账户使用的区域不是 datadoghq.com，请添加 DD_SITE。Depot 会将每次工作流运行及其任务和步骤直接作为流水线发送到 Datadog。报告采用尽力而为方式，因此 Datadog 故障不会导致 CI 运行失败。

运行、监控和调试运行

常用的排查和检查命令：

# Find recent/failed runs (defaults to queued + running)
depot ci run list
depot ci run list --status failed -n 10
depot ci run list --repo depot/api --status failed --pr 42

# Inspect a run's full workflow -> job -> attempt hierarchy
depot ci status <run-id>

# Wait for completion; exit 1 if the run fails or is cancelled
depot ci status <run-id> --wait --output json

# Pull logs (accepts run, job, or attempt ID; auto-selects the job if only one)
depot ci logs <run-id>
depot ci logs <run-id> --job build
depot ci logs <job-id> --follow

# Group and explain a run's failures, with a suggested fix per group
depot ci diagnose --run <run-id>

# Inspect parsed test results (Depot CI or GitHub Actions)
depot tests <attempt-id> --ci --status failed

完整命令索引见 references/runs-and-debugging.md：

命令	用途
depot ci run list	列出运行记录（排查入口）；可按状态、仓库、sha、触发器、PR 筛选
depot ci run show	查看单次运行的扁平记录
depot ci workflow list	列出工作流执行记录及各任务计数；可使用 --name 筛选
depot ci workflow show	查看一个工作流的执行记录、任务和尝试
depot ci status	查看完整的运行 → 工作流 → 任务 → 尝试层级结构
depot ci logs	获取任务日志或使用 --follow 实时查看；支持 JSON/JSONL 导出
depot ci summary	获取某次尝试的 GitHub Actions 步骤摘要 Markdown
depot ci metrics	查看某次尝试、任务或运行的 CPU 和内存利用率
depot ci artifacts	使用 list 列出运行产物，并按 ID 使用 download 下载
depot ci diagnose	诊断失败的运行/工作流/任务/尝试，并按组列出失败原因和修复方法
depot tests	列出解析后的测试结果；使用 --ci 或 --gha，并按状态/套件/测试筛选
depot ci ssh	进入运行中任务的沙盒，打开交互式终端
depot ci cancel	取消整个运行、某个工作流或单个任务
depot ci rerun	重新运行工作流中所有处于终止状态的任务
depot ci retry	重试一个失败/已取消的任务；--failed 还会重新运行下游任务

如需完整的标志表、JSON 输出结构，或上述排查示例中未列出的命令，请阅读 references/runs-and-debugging.md。

测试结果和基于耗时的拆分

使用 depot tests 检查解析后的 JUnit 结果。使用 depot tests split、depot tests run 或 depot tests report，根据历史耗时平衡测试并上传新报告。这三个子命令只能在 Depot CI 或 Depot GitHub Actions 运行器任务中运行。

有关候选项身份规则、矩阵行为、报告要求和命令示例，请阅读 references/test-splitting.md。

与 GitHub Actions 的兼容性

Depot CI 会执行 GitHub Actions YAML 工作流。兼容性并非完全一致，存在一些限制。完整的支持与兼容性列表见 references/github-actions-compatibility.md。

在需要回答或处理以下问题或类似问题时，请阅读兼容性参考：

• 是否支持特定的工作流级、作业级或步骤级字段，例如 concurrency、jobs.<id>.environment、jobs.<id>.snapshot、jobs.<id>.container、jobs.<id>.services、jobs.<id>.strategy.matrix、steps[*].shell。
• 是否接受某个触发事件：受支持的列表（push、pull_request、pull_request_target、pull_request_review、pull_request_review_comment、issue_comment、deployment_status、repository_dispatch、schedule、workflow_call、workflow_dispatch、workflow_run、merge_group），以及 Depot CI 会拒绝的仅限 GitHub 的事件（例如 release、issues、deployment、branch_protection_rule）。
• 可用的表达式上下文（github、env、vars、secrets、needs、strategy、matrix、steps、job、runner、inputs、depot）和函数（always()、success()、failure()、cancelled()、case()、contains()、startsWith()、endsWith()、format()、join()、toJSON()、fromJSON()、hashFiles()）。
• 哪些 permissions 范围可用（actions、checks、code-quality、contents、id-token、issues、packages、pull-requests、security-events、statuses）。请显式请求 code-quality，因为 read-all 和 write-all 不包含此项。
• 可运行的操作类型（JavaScript Node 12/16/20/24、Composite、Docker）。
• Depot CI 支持哪些 runs-on Depot 运行器标签和沙盒规格（仅支持 x86_64 和 Arm，不支持 macOS 或 Windows），以及如何处理无法识别的标签。
• 诊断 depot ci migrate 为何自动禁用了某个作业、从 on: 中移除了某个触发器，或重新映射了某个 runs-on 标签。
• 如何使用受支持的引用和仓库访问权限调用跨仓库可复用工作流。
• 为已知的不受支持功能（由 fork 触发的 PR、部署环境）推荐变通方案。

对于不依赖特定 GHA 功能的常规迁移、运行、密钥或调试任务，无需加载 references/github-actions-compatibility.md。

目录结构

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

常见错误

错误	修正
迁移后删除 .github/workflows/	在过渡期间保留这些文件，以验证 Depot CI 的一致性
为跨仓库可复用工作流使用分支引用	使用完整的提交 SHA 或受支持的版本标签；参见兼容性参考
认为分支／环境变体需要使用控制面板	CLI 可通过 --repo／--env／--branch／--workflow 选择器直接管理变体
在错误的组织上下文中运行	检查 depot org show，使用 depot org list 列出组织，然后切换组织或传入 --org <id>
有多个组织时忘记 --org 标志	迁移或运行命令可能会遗漏预期的仓库／工作流；请指定 --org <id>
工作流使用 Windows 或 macOS 运行器标签	Depot CI 支持 Ubuntu 沙盒；迁移前请选择兼容的作业和运行器