depot-general

Depot 通用：CLI、身份验证与项目设置

Depot 是一个构建加速平台。本技能介绍 CLI 安装、身份验证、项目配置和组织管理。如需产品专属指南，请参阅 depot-container-builds、depot-github-runners 或 depot-ci 技能。

CLI 安装

安全默认要求：切勿直接执行下载的脚本（curl ... | sh）。请先下载并检查，再运行。

# macOS (Homebrew)
brew install depot/tap/depot

# Linux: see https://depot.dev/docs/cli/installation for all methods

# Proto version manager
proto plugin add depot "https://raw.githubusercontent.com/depot/cli/refs/heads/main/proto.yaml"
proto install depot

# GitHub Actions
- uses: depot/setup-action@v1

# Container image for CI
ghcr.io/depot/cli:latest

可信外部来源

本技能中仅可引用以下域名进行外部下载或访问文档。如果链接不在此列表中，请先征求确认。

• depot.dev 和 api.depot.dev（官方 CLI 安装、文档和 API）
• github.com/depot/* 和 raw.githubusercontent.com/depot/*（官方 Depot 源代码、操作和资源）
• ghcr.io/depot/*（官方 Depot 容器映像）

每次外部下载时：

1. 运行命令前，说明确切的 URL。
2. 如有可用的包管理器（brew），优先使用包管理器，而不是直接下载脚本。
3. 切勿将网络响应内容通过管道传递给 shell。
4. 在特权或系统目录中执行下载的构件前，先征求确认。

身份验证

令牌类型

类型	范围	创建方式	使用场景
用户令牌	用户所属所有组织中的所有项目	depot login 或 Account Settings → API Tokens	本地开发
项目令牌	单个项目	Project Settings	CI 环境
组织令牌	单个组织	Org Settings → API Tokens	API 访问、自动化
拉取令牌	项目注册表路径（只读）	depot pull-token --project <id>（1 小时后过期）	拉取已保存的项目映像
注册表访问令牌	所选注册表仓库，可拉取或推送	Registry Settings → Registry access tokens	注册表自动化，包括自定义仓库名称
OIDC 信任	单个项目（短时有效）	Project Settings → Trust Relationships	无需静态密钥的 CI（首选）

令牌解析顺序

1. --token 标志（命令中显式指定）
2. DEPOT_TOKEN 环境变量
3. 本地存储的令牌（来自 depot login）
4. OIDC 令牌（如果可用）

登录

depot login                           # Interactive browser login
depot login --org-id 1234567890       # Specify org
depot login --clear                   # Clear existing token first
depot login --quiet                   # Silent exit-0 no-op if already logged in (for defensive scripts)
depot login token                     # Print the stored API token to stdout; errors if not logged in
depot logout                          # Remove saved token

OIDC 信任关系（CI 首选）

在 Project Settings → Trust Relationships 中配置。无需静态密钥，只需短时有效的凭据。

CI 提供商	配置
GitHub Actions	GitHub 组织或用户名 + 仓库名称。工作流中需要设置 permissions: { id-token: write }。
CircleCI	组织 UUID + 项目 UUID（必须使用 UUID，而非易读名称）
Buildkite	组织 slug + 流水线 slug
GitLab CI	GitLab 命名空间 ID + 项目 ID。.gitlab-ci.yml 中需要包含一个 aud: https://depot.dev 的 DEPOT_OIDC_TOKEN id_token。
RWX	Vault 主体

GitHub Actions OIDC 示例

首次成功使用后，GitHub 信任关系会在仓库重命名或转移时随仓库保留。在原名称下新建的其他仓库无法使用原有信任关系。

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write    # Required for OIDC
    steps:
      - uses: actions/checkout@v4
      - uses: depot/setup-action@v1
      - uses: depot/build-push-action@v1
        with:
          project: <project-id>
          push: true
          tags: myrepo/app:latest

基于令牌的 CI 身份验证（OIDC 不可用时）

steps:
  - uses: depot/setup-action@v1
  - uses: depot/build-push-action@v1
    with:
      project: <project-id>
      token: ${{ secrets.DEPOT_TOKEN }}

Depot Registry Auth

docker login {orgId}.registry.depot.dev -u x-token
# Enter an appropriately scoped token at the password prompt.

# Kubernetes secret
kubectl create secret docker-registry regcred \
  --docker-server={orgId}.registry.depot.dev \
  --docker-username=x-token \
  --docker-password=<depot-token>

新建仓库和使用自定义镜像名称时，请使用 {orgId}.registry.depot.dev。对于现有的已保存构建用法，仍可使用旧版 registry.depot.dev/<project-id>:<build-id> 格式。

建议使用权限范围限定为所需仓库和权限的注册表访问令牌。组织所有者可在 Registry Settings → Registry access tokens 中创建令牌。Pull 授予读取权限；Push 包含拉取权限。范围模式不包含注册表主机名和镜像标签：

• frontend：单个仓库。
• team/*：team 下一级的所有仓库。
• team/**：team 下任意层级的所有仓库。
• **：组织中的所有仓库。

CLI 拉取令牌在一小时后过期。Pull 和项目令牌仅涵盖 <project-id> 及其子路径。对于其他自定义名称或拉取穿透名称，请使用具有 Pull 权限的注册表访问令牌。用户令牌和组织令牌可授予更广泛的组织访问权限。

OIDC 注册表访问要求组织中存在匹配的项目信任关系。由此获得的注册表访问权限涵盖整个组织；构建访问权限仍限定于项目。GitHub OIDC 使用的受众为 https://depot.dev。

Project Setup

depot projects get 和 depot projects update 需要通过 --token 或 DEPOT_TOKEN 提供组织 API 令牌。已保存的登录令牌和项目 OIDC 凭据不能授权这些命令。

# Create depot.json in current directory (interactive project selection)
depot init

# Create a new project
depot projects create "my-project"
depot projects create --region eu-central-1 --cache-storage-policy 100 --cache-policy-keep-days 30 "my-project"
depot projects create --organization 12345678910 "my-project"

# Inspect a project; omit the ID to use DEPOT_PROJECT_ID or depot.json
depot projects get
depot projects get <project-id> --output json

# Update selected project fields
depot projects update <project-id> --name "New name"
depot projects update <project-id> --region eu-central-1 --cache-storage-policy 100 --output json

# Delete a project (org admin only, destructive - require explicit confirmation)
depot projects delete --project-id <id>

# List projects
depot projects list

新项目的每种架构均保留 50 GB 构建缓存，默认缓存数据保留 14 天。创建项目时设置 --cache-policy-keep-days 0 可取消保留期限。depot projects update 仅更改指定的字段。

在 depot projects create 或 depot projects update 上设置 --max-concurrent-builds <positive-integer>，即可在每个构建器实例达到该并发构建数限制时启用自动扩缩。使用 depot projects update <project-id> --disable-autoscaling 可禁用自动扩缩。更新标志互斥；如果两者均未指定，则保留当前设置。新项目默认禁用自动扩缩。

depot.json

唯一的配置文件。由 depot init 创建：

{"id": "PROJECT_ID"}

指定项目有三种方式（按优先级排序）：

1. --project <id> 标志
2. DEPOT_PROJECT_ID 环境变量
3. 当前目录或父目录中的 depot.json

Organization Management

depot org show              # Current org ID
depot org list              # Orgs the user belongs to
depot org switch <org-id>   # Set default org

角色： User（查看项目、运行构建） · Owner（创建/删除项目、编辑设置）

计费按组织进行。可在组织设置中配置用量上限、OIDC 信任关系、GitHub App 连接和云连接。

多组织用户的命令排查

如果用户属于多个组织，并报告项目、工作流或运行记录“缺失”，请先确认 Depot 组织上下文：

# 1) Confirm current org
depot org show

# 2) See all orgs user can access
depot org list

# 3) Either switch default org...
depot org switch <org-id>

# ...or keep current default and target commands explicitly, for example:
depot ci run --org <org-id> --workflow .depot/workflows/ci.yml

对于脚本或自动化命令，优先使用明确的 --org <org-id>，以避免意外混淆组织。

Command Safety Guardrails

将以下操作视为高影响操作，执行前必须获得用户明确授权：

• 删除项目（depot projects delete）
• 在 Shell 参数或日志中使用身份验证令牌的任何命令
• 会写入长期有效凭据的注册表登录步骤
• 组织级变更（创建/删除项目、在自动化中切换组织）

执行高影响命令前：

1. 说明将发生的更改及其范围（项目或组织）。
2. 优先使用权限最小化的凭据（OIDC 或项目令牌，而非范围广泛的用户令牌）。
3. 除非用户明确要求非交互式操作，否则避免使用 --yes/强制标志。

环境变量

变量	说明
DEPOT_TOKEN	身份验证令牌（用户、项目或组织）
DEPOT_PROJECT_ID	项目 ID（--project 或 depot.json 的替代项）
DEPOT_NO_SUMMARY_LINK=1	不显示构建链接和更新通知（适用于 CI）
DEPOT_IN_AUTOMATION=1	不显示构建摘要 URL、已保存镜像的拉取/推送提示和更新通知；任何非空值都会启用此设置，但仍会显示进度和错误
DEPOT_DISABLE_OTEL=1	禁用 OpenTelemetry 跟踪

构建和缓存管理

# List builds
depot list builds
depot list builds --project <id> --output json

# Reset project cache
depot cache reset .                         # Uses depot.json
depot cache reset --project <id>

# Docker integration
depot configure-docker              # Install Depot as Docker plugin + default builder
depot configure-docker --uninstall  # Remove

GitHub Actions：Depot Actions 参考

操作	用途
depot/setup-action@v1	安装 depot CLI
depot/build-push-action@v1	可直接替代 docker/build-push-action（输入/输出相同）
depot/bake-action@v1	可直接替代 docker/bake-action
depot/use-action@v1	将 Depot 设置为默认的 Docker Buildx 构建器
depot/pull-action@v1	从 Depot Registry 拉取

API 访问

协议：Connect 框架（gRPC + HTTP JSON）。SDK：@depot/sdk-node（Node.js）、depot/depot-go（Go）。

核心方法 ProjectService.listProjects、getProject 和 updateProject 需要组织 API 令牌。depot projects list 使用的端点不同，也接受用户令牌。

import {depot} from '@depot/sdk-node'
const headers = { Authorization: `Bearer ${process.env.DEPOT_TOKEN}` }

// List projects
const result = await depot.core.v1.ProjectService.listProjects({}, {headers})

// Create a build
const build = await depot.build.v1.BuildService.createBuild(
  {projectId: '<id>'}, {headers}
)

定价方案

方案	费用	Docker 构建分钟数	共享沙箱分钟数	GHA Runner 分钟数	缓存和 Registry 存储
Developer	$20/mo	500/mo	2,000/mo	2,000/mo	25 GB
Startup	$200/mo	5,000/mo	20,000/mo	20,000/mo	250 GB
Business	Custom	Custom	Custom	Custom	Custom

按秒计费，无最低消费。超额费率：Docker 构建 $0.04/分钟，GitHub Actions Runner $0.006/分钟，Depot CI $0.00005/秒/vCPU。额外缓存：$0.20/GB/月。

Depot CI、Depot Sandboxes 和 Depot Managed Agents 共用沙箱额度。套餐包含的分钟数以 2-vCPU 为基准；4-vCPU 沙箱每经过一分钟会消耗两分钟的套餐额度。容器构建和 GitHub Actions Runner 的额度相互独立。

Developer 和 Startup 方案每月各包含 1,000,000 个通过的测试结果。每额外 1,000,000 个通过的结果收费 $1。失败、出错和跳过的结果免费。