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/月。

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场景（推荐）

depot login # Interactive browser login depot login --org-id 1234567890 # Specify org depot login --clear # Clear existing token first depot logout # Remove saved token

depot login # 交互式浏览器登录 depot login --org-id 1234567890 # 指定组织 depot login --clear # 先清除现有令牌 depot logout # 删除已保存的令牌

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主题

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

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

Variable

Description

DEPOT_TOKEN

Auth token (user, project, or org)

DEPOT_PROJECT_ID

Project ID (alternative to

--project

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追踪

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镜像仓库拉取镜像

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

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

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

All + GPU

方案

费用

构建时长

缓存

运行器

开发者版

$20/月

2000分钟/月

25 GB

Linux、Windows

创业版

$200/月

20000分钟/月 + $0.004/分钟

250 GB

Linux、Windows、macOS

企业版

定制

全部类型 + GPU