depot-general

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Depot General — CLI, Auth, and Project Setup

Depot 通用指南 — CLI、认证与项目设置

Depot is a build acceleration platform. This skill covers CLI installation, authentication, project configuration, and organization management. For product-specific guidance, see the depot-container-builds, depot-github-runners, or depot-ci skills.

Depot是一个构建加速平台。本指南涵盖CLI安装、认证、项目配置和组织管理。如需特定产品相关指导，请查看depot-container-builds、depot-github-runners或depot-ci相关内容。

CLI Installation

CLI安装

bash

undefined

bash

undefined

macOS (Homebrew)

brew install depot/tap/depot

Linux / CI (install script)

Linux / CI (安装脚本)

curl -L https://depot.dev/install-cli.sh | sh

Specific version

指定版本

curl -L https://depot.dev/install-cli.sh | sh -s 2.96.2

Custom install directory

自定义安装目录

curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh

Proto version manager

Proto版本管理器

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

uses: depot/setup-action@v1

Container image for CI

CI用容器镜像

ghcr.io/depot/cli:latest

undefined

ghcr.io/depot/cli:latest

undefined

Authentication

认证

Token Types

令牌类型

Type	Scope	Created Via	Use Case
User token	All projects in all user's orgs	`depot login` or Account Settings → API Tokens	Local development
Project token	Single project	Project Settings	CI environments
Org API token	Single organization	Org Settings → API Tokens	API access, automation
OIDC trust	Single project (short-lived)	Project Settings → Trust Relationships	CI without static secrets (preferred)

类型	适用范围	创建方式	使用场景
用户令牌	用户所有组织中的全部项目	`depot login` 或账户设置 → API令牌	本地开发
项目令牌	单个项目	项目设置	CI环境
组织API令牌	单个组织	组织设置 → API令牌	API访问、自动化
OIDC信任	单个项目（短期有效）	项目设置 → 信任关系	无需静态密钥的CI场景（推荐）

Token Resolution Order

令牌解析优先级

```
--token
```
flag (explicit on command)
Locally stored token (from
```
depot login
```
)
```
DEPOT_TOKEN
```
environment variable

```
--token
```
参数（命令行显式指定）
本地存储的令牌（来自
```
depot login
```
）
```
DEPOT_TOKEN
```
环境变量

Login

OIDC Trust Relationships (Preferred for CI)

OIDC信任关系（CI场景推荐）

Configure in Project Settings → Trust Relationships. No static secrets — short-lived credentials.

CI Provider	Configuration
GitHub Actions	GitHub org/user name + repository name. Requires `permissions: { id-token: write }` in workflow.
CircleCI	Organization UUID + Project UUID (must use UUIDs, not friendly names)
Buildkite	Organization slug + Pipeline slug
RWX	Vault subject

在项目设置 → 信任关系中配置。无需静态密钥，使用短期凭证。

CI提供商	配置方式
GitHub Actions	GitHub组织/用户名 + 仓库名称。工作流中需要配置 `permissions: { id-token: write }` 。
CircleCI	组织UUID + 项目UUID（必须使用UUID，而非友好名称）
Buildkite	组织Slug + 流水线Slug
RWX	Vault主题

GitHub Actions OIDC Example

GitHub Actions OIDC示例

yaml

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

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write    # 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

Token-Based CI Auth (When OIDC Not Available)

基于令牌的CI认证（OIDC不可用时）

yaml

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

yaml

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

Depot Registry Auth

Depot镜像仓库认证

bash

docker login registry.depot.dev -u x-token -p <any-depot-token>

bash

docker login registry.depot.dev -u x-token -p <any-depot-token>

Username is always "x-token". Password is any user, project, org, or OIDC token.

用户名固定为"x-token"。密码可以是任意用户、项目、组织或OIDC令牌。

Kubernetes secret

Kubernetes密钥

kubectl create secret docker-registry regcred
--docker-server=registry.depot.dev
--docker-username=x-token
--docker-password=<depot-token>

undefined

kubectl create secret docker-registry regcred
--docker-server=registry.depot.dev
--docker-username=x-token
--docker-password=<depot-token>

undefined

Project Setup

项目设置

bash

undefined

bash

undefined

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

在当前目录创建depot.json（交互式选择项目）

depot init

Create a new project

创建新项目

depot projects create "my-project" depot projects create --region eu-central-1 --cache-storage-policy 100 "my-project" depot projects create --organization 12345678910 "my-project"

Delete a project (org admin only)

删除项目（仅组织所有者可操作）

depot projects delete --project-id <id> --yes

List projects

列出项目

depot projects list

undefined

depot projects list

undefined

depot.json

The only configuration file. Created by

depot init

json

{"id": "PROJECT_ID"}

Three ways to specify a project (in priority order):

```
depot.json
```
in current or parent directory
```
--project <id>
```
flag
```
DEPOT_PROJECT_ID
```
environment variable

唯一的配置文件，由

depot init

创建：

json

{"id": "PROJECT_ID"}

指定项目的三种方式（优先级从高到低）：

当前目录或父目录中的
```
depot.json
```
```
--project <id>
```
参数
```
DEPOT_PROJECT_ID
```
环境变量

Organization Management

组织管理

bash

depot org list                    # List orgs (supports --output json/csv)
depot org switch [org-id]         # Set current org
depot org show                    # Show current org ID

Roles: User (view projects, run builds) · Owner (create/delete projects, edit settings)

Billing is per-organization. Configure usage caps, OIDC trust relationships, GitHub App connections, and cloud connections from org settings.

bash

depot org list                    # 列出组织（支持--output json/csv格式）
depot org switch [org-id]         # 切换当前组织
depot org show                    # 显示当前组织ID

角色： 用户（查看项目、运行构建）· 所有者（创建/删除项目、编辑设置）

计费按组织维度进行。可在组织设置中配置使用上限、OIDC信任关系、GitHub应用连接和云服务连接。

Environment Variables

环境变量

Variable	Description
`DEPOT_TOKEN`	Auth token (user, project, or org)
`DEPOT_PROJECT_ID`	Project ID (alternative to `--project` or `depot.json` )
`DEPOT_NO_SUMMARY_LINK=1`	Suppress build links and update notices (useful in CI)
`DEPOT_INSTALL_DIR`	Custom CLI install directory
`DEPOT_DISABLE_OTEL=1`	Disable OpenTelemetry tracing

变量名称	说明
`DEPOT_TOKEN`	认证令牌（用户、项目或组织级别）
`DEPOT_PROJECT_ID`	项目ID（替代 `--project` 参数或 `depot.json` 的方式）
`DEPOT_NO_SUMMARY_LINK=1`	禁用构建链接和更新通知（CI场景适用）
`DEPOT_INSTALL_DIR`	自定义CLI安装目录
`DEPOT_DISABLE_OTEL=1`	禁用OpenTelemetry追踪

Build and Cache Management

构建与缓存管理

bash

undefined

bash

undefined

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>

depot cache reset . # 使用当前目录的depot.json depot cache reset --project <id>

Docker integration

Docker集成

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

undefined

depot configure-docker # 安装Depot作为Docker插件并设置为默认构建器 depot configure-docker --uninstall # 卸载

undefined

GitHub Actions — Depot Actions Reference

GitHub Actions — Depot Actions参考

Action	Purpose
`depot/setup-action@v1`	Install `depot` CLI
`depot/build-push-action@v1`	Drop-in for `docker/build-push-action` (same inputs/outputs)
`depot/bake-action@v1`	Drop-in for `docker/bake-action`
`depot/use-action@v1`	Set Depot as default Docker Buildx builder
`depot/pull-action`	Pull from Depot Registry

Action	用途
`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`	从Depot镜像仓库拉取镜像

API Access

API访问

Protocol: Connect framework (gRPC + HTTP JSON). SDKs:

@depot/sdk-node

(Node.js),

depot/depot-go

(Go).

javascript

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}
)

协议：Connect框架（gRPC + HTTP JSON）。SDK：

@depot/sdk-node

（Node.js）、

depot/depot-go

（Go）。

javascript

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

// 列出项目
const result = await depot.core.v1.ProjectService.listProjects({}, {headers})

// 创建构建任务
const build = await depot.build.v1.BuildService.createBuild(
  {projectId: '<id>'}, {headers}
)

Pricing Plans

定价方案

Plan	Cost	Build Minutes	Cache	Runners
Developer	$20/mo	2,000/mo	25 GB	Linux, Windows
Startup	$200/mo	20,000/mo + $0.004/min	250 GB	Linux, Windows, macOS
Business	Custom	Custom	Custom	All + GPU

Per-second billing, no minimums. Additional cache: $0.20/GB/month.

方案	费用	构建时长	缓存	运行器
开发者版	$20/月	2000分钟/月	25 GB	Linux、Windows
创业版	$200/月	20000分钟/月 + $0.004/分钟	250 GB	Linux、Windows、macOS
企业版	定制	定制	定制	全部类型 + GPU

按秒计费，无最低消费。额外缓存费用：$0.20/GB/月。

depot-general

Original

Translation

Depot General — CLI, Auth, and Project Setup

Depot 通用指南 — CLI、认证与项目设置

CLI Installation

CLI安装

macOS (Homebrew)

macOS (Homebrew)

Linux / CI (install script)

Linux / CI (安装脚本)

Specific version

指定版本

Custom install directory

自定义安装目录

Proto version manager

Proto版本管理器

GitHub Actions

GitHub Actions

Container image for CI

CI用容器镜像

Authentication

认证

Token Types

令牌类型

Token Resolution Order

令牌解析优先级

Login

登录

OIDC Trust Relationships (Preferred for CI)

OIDC信任关系（CI场景推荐）

GitHub Actions OIDC Example

GitHub Actions OIDC示例

Token-Based CI Auth (When OIDC Not Available)

基于令牌的CI认证（OIDC不可用时）

Depot Registry Auth

Depot镜像仓库认证

Username is always "x-token". Password is any user, project, org, or OIDC token.

用户名固定为"x-token"。密码可以是任意用户、项目、组织或OIDC令牌。

Kubernetes secret

Kubernetes密钥

Project Setup

项目设置

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

在当前目录创建depot.json（交互式选择项目）

Create a new project

创建新项目

Delete a project (org admin only)

删除项目（仅组织所有者可操作）

List projects

列出项目

depot.json

depot.json

Organization Management

组织管理

Environment Variables

环境变量

Build and Cache Management

构建与缓存管理

List builds

列出构建记录

Reset project cache

重置项目缓存

Docker integration

Docker集成

GitHub Actions — Depot Actions Reference

GitHub Actions — Depot Actions参考

API Access

API访问

Pricing Plans

定价方案