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. ネットワークからのレスポンスをシェルにパイプしてはいけません。
4. ダウンロードした成果物を特権が必要な場所やシステム領域で実行する前に、確認を求めてください。

認証

トークンの種類

種類	スコープ	作成方法	用途
ユーザートークン	ユーザーが所属するすべての組織の全プロジェクト	depot login またはアカウント設定 → API トークン	ローカル開発
プロジェクトトークン	単一のプロジェクト	プロジェクト設定	CI 環境
組織トークン	単一の組織	組織設定 → API トークン	API アクセス、自動化
プルトークン	プロジェクトのレジストリーパス（読み取り専用）	depot pull-token --project <id>（有効期限は 1 時間）	保存済みのプロジェクトイメージのプル
レジストリーアクセストークン	選択したレジストリーリポジトリー、プルまたはプッシュ	レジストリー設定 → レジストリーアクセストークン	カスタムリポジトリー名を含むレジストリーの自動化
OIDC 信頼関係	単一のプロジェクト（短期）	プロジェクト設定 → 信頼関係	静的シークレットを使わない 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 では推奨）

プロジェクト設定 → 信頼関係で設定します。静的シークレットは不要で、有効期間の短い認証情報を使用します。

CI プロバイダー	設定
GitHub Actions	GitHub の組織名またはユーザー名とリポジトリー名。ワークフローで permissions: { id-token: write } が必要です。
CircleCI	組織 UUID とプロジェクト UUID（わかりやすい名前ではなく、UUID を使用する必要があります）
Buildkite	組織のスラッグとパイプラインのスラッグ
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 レジストリ認証

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にはPullアクセスが含まれます。スコープパターンにはレジストリのホスト名とイメージタグを含めません。

• frontend：1つのリポジトリ。
• team/*：teamの直下1階層。
• team/**：team配下の任意の深さ。
• **：組織内のすべてのリポジトリ。

CLIのPullトークンの有効期限は1時間です。Pullトークンとプロジェクトトークンが対象とするのは、<project-id>とその配下のパスのみです。その他のカスタム名またはプルスルー名には、Pull権限を持つレジストリアクセストークンを使用してください。ユーザートークンと組織トークンでは、組織全体へのより広範なアクセスを許可できます。

OIDCによるレジストリアクセスには、組織内で一致するプロジェクトの信頼関係が必要です。これにより付与されるレジストリアクセスは組織全体を対象としますが、ビルドアクセスはプロジェクトのスコープに限定されます。GitHub OIDCでは、オーディエンスとしてhttps://depot.devを使用します。

プロジェクトのセットアップ

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

プロジェクトを指定する方法は3つあります（優先順位順）。

1. --project <id>フラグ
2. DEPOT_PROJECT_ID環境変数
3. 現在のディレクトリまたは親ディレクトリにあるdepot.json

組織の管理

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>を指定してください。

コマンド実行の安全対策

以下は影響の大きい操作として扱い、実行前にユーザーの明示的な意図を確認してください。

• プロジェクトの削除（depot projects delete）
• シェル引数やログで認証トークンを使用するコマンド
• 長期間有効な認証情報を書き込むレジストリログイン手順
• 組織レベルの変更（プロジェクトの作成／削除、自動化での組織切り替え）

影響の大きいコマンドを実行する前に、次の点を確認してください。

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）。

コア API の 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 ランナー分数	キャッシュとレジストリのストレージ
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	カスタム	カスタム	カスタム	カスタム	カスタム

秒単位の課金で、最低利用料金はありません。超過料金：Docker ビルドは $0.04/分、GitHub Actions ランナーは $0.006/分、Depot CI は $0.00005/秒/vCPU です。追加キャッシュは $0.20/GB/月です。

Depot CI、Depot Sandboxes、Depot Managed Agents は、サンドボックスの利用枠を共有します。含まれる分数は 2 vCPU を基準とし、4 vCPU のサンドボックスでは経過時間 1 分につき含まれる分数を 2 分消費します。コンテナのビルドと GitHub Actions ランナーの利用枠は別々です。

Developer プランと Startup プランには、毎月 1,000,000 件の合格したテスト結果が含まれます。追加の合格結果は 1,000,000 件につき $1 です。不合格、エラー、スキップの結果は無料です。