From c6b2065876373d50c26711f6a02cd7a4bea4f6d1 Mon Sep 17 00:00:00 2001 From: andie787 <13827355+andie787@users.noreply.github.com> Date: Thu, 7 May 2026 00:42:26 +0000 Subject: [PATCH] Update docs content from https://github.com/depot/app --- content/cache/authentication.mdx | 6 +- content/cache/integrations/github-actions.mdx | 22 +- .../manage-secrets-and-variables.mdx | 245 +++--- .../ci/how-to-guides/manage-workflow-runs.mdx | 105 ++- content/ci/oidc.mdx | 34 +- content/ci/overview.mdx | 2 +- content/cli/authentication.mdx | 30 +- content/cli/reference/depot-ci.mdx | 704 ++++++++++++++++-- .../github-actions/integrations/dagger.mdx | 7 + content/integrations/tailscale.mdx | 2 + content/registry/overview.mdx | 34 +- content/registry/pull-through-cache.mdx | 73 ++ 12 files changed, 1064 insertions(+), 200 deletions(-) create mode 100644 content/registry/pull-through-cache.mdx diff --git a/content/cache/authentication.mdx b/content/cache/authentication.mdx index 1f8b957..b91893d 100644 --- a/content/cache/authentication.mdx +++ b/content/cache/authentication.mdx @@ -4,9 +4,9 @@ ogTitle: Authentication for Depot remote caching description: Learn how to authenticate with Depot remote caching --- -Depot Cache supports authenticating with **user** tokens and **organization** tokens. Additionally, [Depot-managed GitHub Actions runners](/docs/github-actions/overview) are pre-configured with single-use job tokens. +Depot Cache supports authenticating with **user** tokens and **organization** tokens. Additionally, [Depot GitHub Actions runners](/docs/github-actions/overview) are pre-configured with a token that is active for a single job, which is set as environment variable called `DEPOT_CACHE_TOKEN`. -Project tokens are **not** supported for Depot cache. +Project tokens are **not** supported for Depot cache because only [container builds](/docs/container-builds/overview) use projects. ## Token types @@ -14,7 +14,7 @@ Project tokens are **not** supported for Depot cache. - **Organization tokens** are used to authenticate as an organization. These tokens can be generated from your organization's settings page. -- **Depot GitHub Actions runners** are pre-configured with single-use job tokens. If you are using the automatic Depot Cache integration with Depot runners, you do not need to manually configure authentication. +- **Depot GitHub Actions runners** are pre-configured with a token that is active for a single job (`DEPOT_CACHE_TOKEN`). If you are using the automatic Depot Cache integration with Depot runners, you do not need to manually configure authentication. ## Configuring build tools diff --git a/content/cache/integrations/github-actions.mdx b/content/cache/integrations/github-actions.mdx index 979c910..ac68819 100644 --- a/content/cache/integrations/github-actions.mdx +++ b/content/cache/integrations/github-actions.mdx @@ -4,27 +4,27 @@ ogTitle: Remote caching for GitHub Actions workflows description: Learn how to use Depot remote caching for GitHub Actions workflows --- -[**Depot Cache**](/docs/cache/overview) provides a remote cache service for GitHub Actions cache when running workflows on Depot-managed GitHub Actions runners, which provides faster upload and download speeds compared to the standard GitHub Actions cache. +[**Depot Cache**](/docs/cache/overview) provides a remote cache service for GitHub Actions cache when running workflows on Depot GitHub Actions runners, which provides faster upload and download speeds compared to the standard GitHub Actions cache. ## Use GitHub Actions cache with Depot Cache Depot Cache for GitHub Actions is only available when using [Depot GitHub Actions runners](/docs/github-actions/overview). Standard GitHub-hosted runners or self-hosted runners use the standard GitHub Actions cache. -### From Depot-managed Actions runners +### From Depot GitHub Actions runners -[Depot GitHub Actions runners](/docs/github-actions/overview) are pre-configured to use Depot Cache for all GitHub Actions cache operations. When running workflows on Depot runners, any action that uses the GitHub Actions cache API automatically uses Depot Cache instead of the standard GitHub Actions cache. +[Depot GitHub Actions runners](/docs/github-actions/overview) are pre-configured to use Depot Cache for all GitHub Actions cache operations. When running workflows on Depot GitHub Actions runners, any action that uses the GitHub Actions cache API automatically uses Depot Cache instead of the standard GitHub Actions cache. This includes: -- `actions/cache` - The standard caching action -- `actions/setup-node` - Caches npm/yarn dependencies when you enable the cache option -- `actions/setup-python` - Caches pip dependencies when you enable the cache option -- `actions/setup-java` - Caches Maven/Gradle dependencies when you enable the cache option +- `actions/cache`: the standard caching action +- `actions/setup-node`: caches npm/yarn dependencies when you enable the cache option +- `actions/setup-python`: caches pip dependencies when you enable the cache option +- `actions/setup-java`: caches Maven/Gradle dependencies when you enable the cache option - Any other action that uses the GitHub Actions cache API #### Example workflow -A workflow using `actions/cache` automatically uses Depot Cache when running on Depot runners, with no changes to your workflow file: +A workflow using `actions/cache` automatically uses Depot Cache when running on Depot GitHub Actions runners, with no changes to your workflow file: ```yaml steps: @@ -44,9 +44,9 @@ steps: ### Compatibility with other tools -Depot Cache works with any tool or package manager that's compatible with the GitHub Actions cache API. When running on Depot runners, these tools automatically use Depot Cache for faster upload and download speeds. +Depot Cache works with any tool or package manager that's compatible with the GitHub Actions cache API. When running on Depot GitHub Actions runners, these tools automatically use Depot Cache for faster upload and download speeds. -For example, you can configure NX to use the GitHub Actions cache through the [`raegen/nx`](https://github.com/raegen/nx) GitHub Action, which directly integrates with the GitHub Actions cache API, or by using the [`@nx/shared-fs-cache`](https://nx.dev/docs/reference/remote-cache-plugins/shared-fs-cache/overview) package combined with `actions/cache` to manually save and restore the `.nx/cache` directory. +For example, you can configure NX to use the GitHub Actions cache by using the [`@nx/shared-fs-cache`](https://nx.dev/docs/reference/remote-cache-plugins/shared-fs-cache/overview) package combined with `actions/cache` to save and restore the `.nx/cache` directory. Other build tools and package managers that integrate with GitHub Actions cache similarly work with Depot Cache without additional configuration. @@ -67,4 +67,4 @@ Depot Cache doesn't enforce cache isolation based on the branch that runs the jo ### Cache retention and limits -The amount of Depot Cache storage you get depends on [your plan](/pricing). You can configure a cache retention policy (7, 14, or 30 days) and size limits (25 GB to 500 GB, or no limit) in your [organization settings](https://depot.dev/orgs/_/settings). The default cache retention policy is 14 days. +The amount of Depot Cache storage you get depends on [your plan](/pricing). You can configure a cache retention policy (7, 14, or 30 days) and size limits (25 GB to 500 GB, or no limit) in your [organization settings](/orgs/_/settings). The default retention policy is 14 days with no size limit. diff --git a/content/ci/how-to-guides/manage-secrets-and-variables.mdx b/content/ci/how-to-guides/manage-secrets-and-variables.mdx index a50e2f5..194a929 100644 --- a/content/ci/how-to-guides/manage-secrets-and-variables.mdx +++ b/content/ci/how-to-guides/manage-secrets-and-variables.mdx @@ -4,24 +4,16 @@ ogTitle: How to manage secrets and variables in Depot CI description: Learn how to add and remove secrets and environment variables for use in your Depot CI workflows. --- -Secrets and variables in Depot CI are scoped to your Depot organization or to a single repository. Repository-scoped secrets override org-wide secrets with the same -name. +Store secrets and variables used by your workflows in Depot CI. You can limit availability of secrets and variables by repository, branch, workflow, and environment. You can also create variants of secrets and variables with different values depending on the availability you define. -Organization owners can manage secrets and variables from the Depot CI [**Settings**](https://depot.dev/orgs/_/workflows/settings) in the dashboard or from the CLI. - -- Add org-wide or repo-specific secrets and variables. -- View all org-wide or repo-specific secrets and variables. -- Remove secrets and variables. - -You can't view secret values after you create them. Variable values are plain text and visible in the dashboard and CLI output. - -Names must be non-empty and repository-scoped names can't contain a forward slash (`/`). +Organization owners manage secrets and variables from the [Depot CI Settings](https://depot.dev/orgs/_/workflows/settings) in the dashboard or from the CLI. ## How secrets are used in workflows When a Depot CI job starts, secrets are decrypted on demand and dispatched to the sandbox in an isolated VM. The sandbox hydrates the environment with those secrets on a per-step basis as configured in your workflow YAML. -Within an organization, repository-scoped secrets take precedence over org-scoped secrets with the same name. A repository-scoped secret is available only to jobs running for that repository. Secret values are masked in all log output. +Within an organization, a repository-scoped secret is available only to jobs running for that repository. When multiple secrets have the same name, Depot chooses +the most specific matching variant for the job's repository, environment, branch, and workflow file. Secret values are masked in all log output. For more information about secret encryption and access control, see [Understanding security in Depot CI](/docs/security#understanding-security-in-depot-ci). @@ -35,120 +27,195 @@ depot ci migrate secrets-and-vars This creates a one-shot GitHub Actions workflow that reads secrets and variables from your GitHub repository and imports them into Depot CI. See [`depot ci migrate secrets-and-vars`](/docs/cli/reference/depot-ci#depot-ci-migrate-secrets-and-vars) in the CLI reference for details. -You can also manage secrets and variables with the Depot CLI. See the [examples](#manage-secrets-and-variables-with-the-cli), or the [full CLI reference](/docs/cli/reference/depot-ci) for all flags and options. +## Manage secrets -## Add secrets to Depot CI using the dashboard +You need to be an [organization owner](/docs/account#organization-access-roles) to manage secrets. Use the dashboard to create secrets and variables and optionally limit availability by repository, branch, workflow, or environment. -1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. -2. In the **Secrets** section, under **Set secret**, use the **Applies to** dropdown to choose the scope. -3. Enter a **Name** and **Value** for the secret. Optionally add a **Description**. -4. Click **Set secret**. +You can also add and remove secrets and variables using the [Depot CLI](/docs/cli/reference/depot-ci), but you can only scope by repository. To create variants and limit availability by branch, workflow, or environment, you need to use the dashboard. + +You can't view secret values after you create them. Variable values are plain text and visible in the dashboard and CLI output. + +Names must be non-empty and repository-scoped names can't contain a forward slash (`/`). -## Remove secrets in Depot CI using the dashboard +### Add a secret -1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon. -2. In the **Secrets** section, find the secret you want to remove and click its actions menu. -3. Select **Remove secret** and click **Remove** to confirm. +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Secrets**. +3. Click **Create secret**. +4. Enter a **Name**, optional **Description**, and **Value** for the secret. +5. Optional: Limit availability by repository, branch name, workflow file, or environment. +6. Click **Create secret**. -## Add variables to Depot CI using the dashboard +### Add a variable -1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon. -2. In the **Variables** section, under **Set variable**, use the **Applies to** dropdown to choose the scope. -3. Enter a **Name** and **Value** for the variable. Optionally add a **Description**. -4. Click **Set variable**. +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Variables**. +3. Click **Create variable**. +4. Enter a **Name**, optional **Description**, and **Value** for the variable. +5. Optional: Limit availability by repository, branch name, workflow file, or environment. +6. Click **Create variable**. -## Remove variables in Depot CI using the dashboard +### Update secrets and variables -1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon. -2. In the **Variables** section, find the variable you want to remove and click its actions menu. -3. Select **Remove variable** and click **Remove** to confirm. +You can update a secret or variable's description, value, and availability from the dashboard. -## Update secrets and variables in Depot CI using the dashboard +You can't view secret values after you create a secret, so you can only enter a new value, not view the current value. -You can update only the description of a secret or variable from the dashboard. +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Secrets** or **Variables**. +3. Find the secret or variable and click its actions menu. +4. Select **Edit**. +5. Update the fields and click **Save**. -To update a secret or variable value, set it again with the same name. The new value overwrites the old one. +### Remove secrets and variables -To update a description: +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Secrets** or **Variables**. +3. Find the secret or variable you want to remove and click its actions menu. +4. Select **Delete**. -1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon. -2. Find the secret or variable and click its actions menu. -3. Select **Edit description**. -4. Update the description and click **Save**. +## Limit availability of secrets and variables -## Manage secrets and variables with the CLI +When you create or edit a secret or variable, you can limit its availability by defining the repository, branch, workflow, and environment to which it belongs. This is useful for security-sensitive credentials and configuration where you want to follow the principle of least privilege. -The Depot CLI supports managing both org-wide and repo-scoped secrets and variables. Repo-scoped secrets and variables override org-wide ones with the same name. +For example, a deployment key in an open source repository might only be needed by deployment workflows, production environments, or release branches. +Limiting that secret to trusted contexts keeps it out of untrusted pull request jobs that could try to print secrets from a modified workflow. -For the full list of flags and options, see the [CLI reference](/docs/cli/reference/depot-ci). +Limit availability using one or more kinds of rule: -### Examples: Managing secrets with the CLI +- **Repository**: Use when the repository matches (select from the available repos). +- **Branch**: Use when the branch name matches. +- **Workflow**: Use when the workflow file matches. +- **Environment**: Use when the job's GitHub environment name matches exactly. Provides compatibility with GitHub Environment Secrets. -Secrets are available in workflows as `${{ secrets.SECRET_NAME }}`. Secret values are encrypted and can't be read back after creation. +Both branch and workflow rules support glob patterns. For example, `release/*` or `deploy-*.yaml`. -```bash -# Add an org-wide secret (prompts for value) -depot ci secrets add MY_API_KEY +Availability gets stricter when you add different kinds of rules and broader when you add alternatives within the same kind of rule. For example, a secret with the following rules: -# Add an org-wide secret with value inline -depot ci secrets add MY_API_KEY --value "secret-value" +- Branch rule main +- Branch rule +- Environment rule production -# Add multiple secrets using KEY=VALUE pairs -depot ci secrets add GITHUB_TOKEN=ghp_xxx MY_API_KEY=secret-value +is accessible only when the branch matches main _or_ _and_ the `environment` field in the workflow YAML matches production. -# Add a repo-scoped secret -depot ci secrets add DATABASE_URL --repo owner/repo --value "postgres://..." +### Using environment rules -# Add a secret with a description -depot ci secrets add MY_API_KEY --value "secret-value" --description "API key for payment provider" +An environment rule matches the job's `environment` field in your workflow YAML. Use an environment rule when a value should be available only to jobs that explicitly run in +an environment such as `staging` or `production`. -# List org-wide secrets -depot ci secrets list +For example, an environment rule with the value production matches the `deploy` job in the following workflow snippet. -# List org-wide and repo-scoped secrets together -depot ci secrets list --repo owner/repo +```yaml +name: Deploy -# Remove one or more secrets (prompts for confirmation) -depot ci secrets remove MY_API_KEY -depot ci secrets remove MY_API_KEY DATABASE_URL +on: + push: + branches: + - main -# Remove a repo-scoped secret -depot ci secrets remove DATABASE_URL --repo owner/repo +jobs: + deploy: + runs-on: depot-ubuntu-24.04 + environment: production + steps: + - uses: actions/checkout@v4 + - run: ./scripts/deploy.sh +``` + +You can also use the object form when you want to attach environment metadata: -# Remove without confirmation -depot ci secrets remove MY_API_KEY --force +```yaml +jobs: + deploy: + runs-on: depot-ubuntu-24.04 + environment: + name: production + url: https://app.example.com ``` -### Examples: Managing variables with the CLI +Depot uses the environment `name` for rule matching. -Variables are available in workflows as `${{ vars.VARIABLE_NAME }}`. Their values can be read back via the CLI. +Jobs without an `environment` field do not match environment rules, even if they run on the same branch or in the same workflow file. -```bash -# Add an org-wide variable (prompts for value) -depot ci vars add SERVICE_NAME +## Secret and variable variants -# Add an org-wide variable with value inline -depot ci vars add SERVICE_NAME --value "api" +Variants let one secret or variable name resolve to different values depending on the [workflow availability](#limit-availability-of-secrets-and-variables) you define (by repository, branch, workflow file, environment). -# Add multiple variables at once using KEY=VALUE pairs -depot ci vars add REGION=us-east-1 ENV=prod +Use variants when the workflow should receive a different value depending on where it runs. For example, you can create: -# Add a repo-scoped variable -depot ci vars add DEPLOY_ENV --repo owner/repo --value "production" +- A default `DATABASE_URL` secret or variable for all repositories. +- A release `DATABASE_URL` secret or variable selected by a branch rule. +- A repository-specific `DATABASE_URL` secret or variable. +- A production `DATABASE_URL` secret or variable selected by an environment rule. -# List org-wide variables -depot ci vars list +You can create, view, and manage all of these variants in the dashboard: -# List org-wide and repo-scoped variables together -depot ci vars list --repo owner/repo +![Multiple variants for DATABASE_URL secret in Depot CI](/images/docs/depot-ci-secrets-example.png) -# Remove one or more variables (prompts for confirmation) -depot ci vars remove SERVICE_NAME -depot ci vars remove SERVICE_NAME DEPLOY_ENV +The dashboard always displays variants sorted from least specific to most specific. -# Remove a repo-scoped variable -depot ci vars remove DEPLOY_ENV --repo owner/repo +### Add a variant using the dashboard -# Remove without confirmation -depot ci vars remove SERVICE_NAME --force -``` +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Secrets** or **Variables**. +3. Find the secret or variable and click its actions menu. +4. Click **Add variant**. +5. Enter the new **Value** and optionally update the **Description**. +6. Add rules to limit availability by repository, branch name, workflow file, or environment. +7. Expand the **Secret variants** or **Variable variants** list to view all variants and any conflicts between them. +8. Click **Create secret** or **Create variable**. + +### How multiple variants resolve + +Depot resolves matching variants before a workflow starts. A repository-scoped variant is invisible to all other repositories. + +When multiple variants match a job, the variants resolve from least to most specific and with the following priority from highest to lowest: environment rules, repository scope, branch rules, workflow rules. + +The following table summarizes how variants resolve: + +| Rule type | Priority | Resolution | +| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| Environment | Highest | Beats repository, branch, and workflow rules. An org-wide variant with an environment rule beats a repo-scoped variant without one. | +| Repository scope | High | Beats branch and workflow rules. | +| Branch | Medium | Beats workflow rules. Narrow branch glob patterns beat broad ones. For example, `release/v2` beats `release/*`. | +| Workflow | Low | Narrow workflow file glob patterns beat broad ones. | +| No rules | Lowest | Matches all jobs (fallback value). | + +Combining rule types always increases specificity. A variant with both an environment rule and a repository scope beats a variant with only one of them. This means an org-wide variant with an environment rule beats a repository-scoped variant with no environment rule. To resolve to a different value for a specific repo, create a variant scoped to both the repository and the environment. + +#### Preview variant resolution in the dashboard + +Use the preview to confirm which variant resolves to your workflow before running it. + +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Secrets** or **Variables**. +3. Click **Preview variant resolution** to toggle it on. +4. Click a name to expand the secret or variable. +5. Enter the workflow's values to check against (repository, environment, branch, and workflow). + The variant that matches the workflow is highlighted in the variant list. + +## Bulk changes to secrets and variables + +Select multiple secrets or variables to delete them or update their availability rules at once. + +### Bulk delete secrets or variables + +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Secrets** or **Variables**. +3. Select the checkboxes next to each secret or variable you want to delete. +4. Click the trash icon. +5. Click **Delete** to confirm. + +### Bulk edit availability rules + +Use bulk edit to add, remove, or replace availability rules across multiple secrets or variables at once. + +1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon. +2. Click **Secrets** or **Variables**. +3. Select the checkboxes next to each secret or variable you want to update. +4. Click the edit icon. +5. Choose how to apply the changes: + - **Add rules**: adds the rules you specify to all selected items without changing their existing rules. + - **Remove rules**: removes the rules you specify from all selected items. + - **Replace all**: removes all existing rules from all selected items and replaces them with the rules you specify. +6. Specify the rules to apply and click **Save changes**. diff --git a/content/ci/how-to-guides/manage-workflow-runs.mdx b/content/ci/how-to-guides/manage-workflow-runs.mdx index c754fba..8fe34d7 100644 --- a/content/ci/how-to-guides/manage-workflow-runs.mdx +++ b/content/ci/how-to-guides/manage-workflow-runs.mdx @@ -1,30 +1,51 @@ --- title: Manage workflow runs ogTitle: How to manage Depot CI workflow runs -description: Learn how to trigger workflows manually, rerun failed runs, retry individual steps, and cancel in-progress workflow runs in Depot CI. +description: Learn how to run workflows manually, rerun failed workflows, retry failed jobs, and cancel in-progress workflow runs in Depot CI. --- -You can trigger, check status, retry, rerun, and cancel workflow runs from the Depot dashboard and the [Depot CLI](/docs/cli/reference/depot-ci). +You can trigger, check status, retry, rerun, and cancel Depot CI workflow runs from the Depot dashboard and the [Depot CLI](/docs/cli/reference/depot-ci). -## Trigger a workflow on demand +## Run workflows with local changes -### CLI +You can run a workflow locally to test it against changes you're actively working on. You don't need to push to GitHub. -Run any workflow on demand with `depot ci run`: +Run any workflow locally with `depot ci run`. For example: ```shell depot ci run --workflow .depot/workflows/ci.yml ``` -You can target specific jobs with the `--job` flag. For all `depot ci` commands and flags, see the [Depot CLI reference](/docs/cli/reference/depot-ci). +To run a specific job, use the `--job` flag. -#### Run against uncommitted changes +For usage, see the [`depot ci run` docs](/docs/cli/reference/depot-ci#depot-ci-run) or run `depot ci run --help`. -When you run `depot ci run` with local changes, the CLI automatically detects them, uploads a patch, and injects a step into each job to apply that patch after checkout. The run reflects your local state without requiring a push. For branches that exist on the remote, the patch contains only unpushed changes. For local-only branches, the patch is relative to the default branch. +#### How local workflow runs work + +When you run `depot ci run` with local changes, the CLI automatically detects the changes and uploads a patch. For any job that has an `actions/checkout` step, the CLI injects a step into each job to apply that patch after checkout. The run reflects your local state without requiring a push. For branches that exist on the remote, the patch contains only unpushed changes. For local-only branches, the patch is relative to the default branch. Each time you run `depot ci run` locally, the CLI uploads a fresh patch, so you can keep iterating until the workflow passes. -### Dashboard +## Manually trigger workflows + +You can manually trigger workflows that include the `workflow_dispatch` event in the `on` section of the workflow YAML file. + +### Manually trigger a workflow from the CLI + +To run a workflow that uses an `on.workflow_dispatch` trigger, use `depot ci dispatch`. Inputs are validated against the workflow's declared input schema. For example: + +```shell +depot ci dispatch --repo depot/cli --workflow deploy.yml --ref main \ + --input environment=staging --input dry_run=true +``` + +The `--workflow` flag takes the workflow file's basename (for example `deploy.yml`), not the full `.depot/workflows/deploy.yml` path. + +The command outputs the run ID and a link to the Depot dashboard. Use `--output json` to get structured output. + +For usage, see the [`depot ci dispatch` docs](/docs/cli/reference/depot-ci#depot-ci-dispatch) or run `depot ci dispatch --help`. + +### Manually trigger a workflow from the dashboard You can start workflows with an `on.workflow_dispatch` trigger from the Depot dashboard. @@ -35,27 +56,81 @@ You can start workflows with an `on.workflow_dispatch` trigger from the Depot da If you don't specify a branch or tag, the workflow runs against the repository's default branch. -## Retry a failed job +## Retry failed jobs + +You can retry a failed or cancelled job, or every failed and cancelled job in a workflow, without rerunning the successful jobs. + +### Retry a failed job from the CLI + +Retry a single job: + +```shell +depot ci retry --job +``` + +Retry every failed and cancelled job in the workflow: + +```shell +depot ci retry --failed +``` + +Include the `--workflow ` flag for runs with multiple workflows. -You can retry an individual failed or cancelled job without rerunning the entire workflow. +Each retry creates a new attempt. You can see previous attempts with `depot ci status`. + +For usage, see the [`depot ci retry` docs](/docs/cli/reference/depot-ci#depot-ci-retry) or run `depot ci retry --help`. + +### Retry a failed job from the dashboard 1. Go to [Depot CI](https://depot.dev/orgs/_/workflows) and click on the workflow. 2. Click **Retry job** for the job you want to retry. Depot creates a new attempt for that job and queues it immediately. The rest of the workflow continues to run. -## Rerun a workflow +## Rerun workflows + +After a workflow finishes, you can rerun every job in the workflow from scratch, or retry only the failed and cancelled jobs. See [Retry failed jobs](#retry-failed-jobs)). -After a workflow finishes, you can rerun the whole workflow or only the failed and cancelled jobs. +### Rerun a workflow from the CLI + +```shell +depot ci rerun +``` + +For multi-workflow runs, pass `--workflow ` to select which workflow to rerun. A workflow must be in a terminal state (finished, failed, or cancelled) before it can be rerun — cancel it first if it's still running. + +For usage, see the [`depot ci rerun` docs](/docs/cli/reference/depot-ci#depot-ci-rerun) or run `depot ci rerun --help`. + +### Rerun a workflow from the dashboard 1. Go to [Depot CI](https://depot.dev/orgs/_/workflows) and click on the workflow. 2. Do one of the following: - To reset every job to queued and run the entire workflow from scratch, click **Re-run workflow**. - To retry only the failed and cancelled jobs, along with any skipped jobs that depend on them, click **Re-run failed**. Jobs that already succeeded aren't retried. -## Cancel a workflow +## Cancel workflows or jobs + +You can cancel a workflow or an individual job while it's queued or running. You cannot cancel a run. + +### Cancel a workflow or job from the CLI + +The `depot ci cancel` command requires exactly one of `--workflow` or `--job`. You can't cancel an entire run. + +Cancel an entire workflow and all jobs within it: + +```shell +depot ci cancel --workflow +``` + +Cancel a single job: + +```shell +depot ci cancel --job +``` + +For usage, see the [`depot ci cancel` docs](/docs/cli/reference/depot-ci#depot-ci-cancel) or run `depot ci cancel --help`. -You can cancel a workflow or an individual job while it's queued or running. +### Cancel a workflow or job from the dashboard 1. Go to [Depot CI](https://depot.dev/orgs/_/workflows) and click on the workflow. 2. Do one of the following: diff --git a/content/ci/oidc.mdx b/content/ci/oidc.mdx index ab03b7f..76881c5 100644 --- a/content/ci/oidc.mdx +++ b/content/ci/oidc.mdx @@ -116,7 +116,7 @@ The general steps are the same for any OIDC-compatible provider: `permissions: id-token: write` is required in your workflow YAML, the same as GitHub Actions. -What needs to change on the cloud provider side when moving from GitHub Actions to Depot CI: +The following needs to change on the cloud provider side when moving from GitHub Actions to Depot CI: | | GitHub Actions | Depot CI | | ------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | @@ -125,14 +125,34 @@ What needs to change on the cloud provider side when moving from GitHub Actions | Repo/branch scoping | `sub` (encoded in the subject) | `sub` or `repository` + `ref` claims (separate conditions) | | JWKS endpoint | `https://token.actions.githubusercontent.com/.well-known/jwks.json` | `https://identity.depot.dev/keys` | -To migrate: +To use Depot CI with OIDC, follow these steps: 1. Add `https://identity.depot.dev` as a new identity provider in your cloud provider. -2. Create a new trust policy for Depot CI rather than modifying your existing GitHub Actions trust policy. This lets both providers work in parallel during the transition. -3. If your existing trust policy conditions on `sub`, update it to use the new format: `spiffe://identity.depot.dev/org//ci/github///ref//sandbox/`. You will likely want to match on a wildcard depending on how specific you want to be: - - Everything in your GitHub organization: `spiffe://identity.depot.dev/org//ci/github//*` - - A specific repository: `spiffe://identity.depot.dev/org//ci/github///*` - - A specific branch: `spiffe://identity.depot.dev/org//ci/github///ref//sandbox/*` +2. Create a new trust policy for Depot CI. Creating a new policy rather than modifying your existing GitHub Actions trust policy lets both providers work in parallel during the transition. +3. If your existing trust policy conditions on `sub`, update it to use the Depot CI format: + + ``` + spiffe://identity.depot.dev/org//ci/github///ref//sandbox/ + ``` + + For more specific matches, use a wildcard: + - Everything in your GitHub organization: + + ``` + spiffe://identity.depot.dev/org//ci/github//* + ``` + + - A specific repository: + + ``` + spiffe://identity.depot.dev/org//ci/github///* + ``` + + - A specific branch: + + ``` + spiffe://identity.depot.dev/org//ci/github///ref//sandbox/* + ``` ## Token claim reference diff --git a/content/ci/overview.mdx b/content/ci/overview.mdx index 595165e..4b1eb08 100644 --- a/content/ci/overview.mdx +++ b/content/ci/overview.mdx @@ -80,7 +80,7 @@ Your original `.github/` workflows continue running on GitHub in parallel until
    -
  • [Run a workflow against your local working tree](/docs/ci/how-to-guides/manage-workflow-runs#run-against-uncommitted-changes) without pushing to GitHub first.
    • +
  • [Run a workflow against your local working tree](/docs/ci/how-to-guides/manage-workflow-runs#run-workflows-with-local-changes) without pushing to GitHub first.
  • Uncommitted changes are automatically patched into the job after checkout.
  • Pass --job to run a subset of jobs.
diff --git a/content/cli/authentication.mdx b/content/cli/authentication.mdx index a6554c2..ab20d42 100644 --- a/content/cli/authentication.mdx +++ b/content/cli/authentication.mdx @@ -8,16 +8,16 @@ The Depot CLI supports token-based authentication and OIDC trust relationships f ## Tokens -Depot supports [Organization](#organization-tokens), [Project](#project-tokens), and [User](#user-access-tokens) tokens. Each token type grants full access to different Depot services depending on its scope: +Depot supports [Organization](#organization-tokens), [Project](#project-tokens), [User](#user-access-tokens), and [Pull](#pull-tokens) tokens. Each token type grants full access to different Depot services depending on its scope: -| Service | User token | Organization token | Project token | -| ---------------- | ---------- | ------------------ | ------------------- | -| Container Builds | ✅ | ✅ | ✅ (project-scoped) | -| Registry | ✅ | ✅ | ✅ (project-scoped) | -| Depot CI | ✅ | ✅ | — | -| Cache | ✅ | ✅ | — | -| Agents | ✅ | ✅ | — | -| API | ✅ | ✅ | — | +| Service | User token | Organization token | Project token | Pull token | +| ---------------- | ---------- | ------------------ | ------------------- | -------------- | +| Container Builds | ✅ | ✅ | ✅ (project-scoped) | — | +| Registry | ✅ | ✅ | ✅ (project-scoped) | ✅ (read-only) | +| Depot CI | ✅ | ✅ | — | — | +| Cache | ✅ | ✅ | — | — | +| Agents | ✅ | ✅ | — | — | +| API | ✅ | ✅ | — | — | ### User access tokens @@ -53,6 +53,18 @@ To generate a project token: 4. Under **Project Tokens**, enter a token description and click **Create token**. 5. Copy the token and save it securely. You won't be able to retrieve the value again from the dashboard. +### Pull tokens + +Pull tokens are short-lived, read-only tokens scoped to the Depot Registry. They grant pull access only and cannot be used to push images or authenticate any other Depot service. Use them in environments that only need to pull images, like production deployments or CI jobs pulling base images. + +Generate a pull token with the Depot CLI: + +```shell +depot pull-token --project +``` + +Pull tokens expire automatically and are not listed or manageable from the dashboard. + ### Token resolution Most Depot CLI commands accept the `--token` flag, which lets you pass an organization, user, or project token directly. The CLI resolves tokens in the following order: diff --git a/content/cli/reference/depot-ci.mdx b/content/cli/reference/depot-ci.mdx index 6f841dd..ebd1379 100644 --- a/content/cli/reference/depot-ci.mdx +++ b/content/cli/reference/depot-ci.mdx @@ -1,7 +1,7 @@ --- title: 'Depot CLI: Depot CI commands reference' ogTitle: 'Depot CLI: Depot CI commands reference' -description: Reference for all Depot CI CLI commands, including migrate, run, ssh, secrets, vars, status, and logs. +description: Reference for the Depot CI CLI commands for migrating workflows, triggering and monitoring runs, managing secrets and variables, and debugging jobs over SSH. --- Reference for all `depot ci` commands. To install the Depot CLI, see [Installation](/docs/cli/installation). @@ -66,7 +66,7 @@ Copies workflows from `.github/workflows/` into `.depot/workflows/`, applying De depot ci migrate workflows ``` -#### What the command does +#### What `depot ci migrate workflows` does 1. Discovers all workflow files in `.github/workflows/`. 2. Analyzes each workflow for compatibility with Depot CI. @@ -178,9 +178,15 @@ depot ci run --workflow .depot/workflows/ci.yml --job build --ssh-after-step 3 Both `--ssh` and `--ssh-after-step` require exactly one `--job` to be specified. +### What `depot ci run` does + +When you run `depot ci run` with local changes, the CLI automatically detects the changes and uploads a patch. For any job that has an `actions/checkout` step, the CLI injects a step into each job to apply that patch after checkout. The run reflects your local state without requiring a push. For branches that exist on the remote, the patch contains only unpushed changes. For local-only branches, the patch is relative to the default branch. + +Each time you run `depot ci run` locally, the CLI uploads a fresh patch, so you can keep iterating until the workflow passes. + --- -## `depot ci run list` +### `depot ci run list` Lists CI runs for your organization. By default returns the 50 most recent queued and running runs. @@ -190,29 +196,293 @@ depot ci run list Alias: `depot ci run ls`. -### Flags +#### Flags -| Flag | Description | -| ------------------- | ------------------------------------------------------------------------------------------------- | -| `--status ` | Filter by status; can be repeated. Values: `queued`, `running`, `finished`, `failed`, `cancelled` | -| `-n ` | Number of runs to return (default: `50`) | -| `--output json` | Output as JSON instead of a table | -| `--org ` | Organization ID (required when user is a member of multiple organizations) | -| `--token ` | Depot API token | +| Flag | Description | +| --------------------- | ------------------------------------------------------------------------------------------------- | +| `--status ` | Filter by status; can be repeated. Values: `queued`, `running`, `finished`, `failed`, `cancelled` | +| `--repo ` | Filter by repository | +| `--sha ` | Filter by commit SHA prefix | +| `--trigger ` | Filter by trigger event, for example `push` or `workflow_dispatch` | +| `--pr ` | Filter by pull request number (requires `--repo`) | +| `-n ` | Number of runs to return (default: `50`) | +| `--output json` | Output as JSON instead of a table | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | -### Examples +#### Examples + +##### List failed runs: ```bash -# List failed runs depot ci run list --status failed +``` + +##### List failed runs for a pull request: + +```bash +depot ci run list --repo depot/api --status failed --pr 42 +``` -# List finished and failed runs +##### List workflow dispatch runs: + +```bash +depot ci run list --trigger workflow_dispatch +``` + +##### List finished and failed runs: + +```bash depot ci run list --status finished --status failed +``` + +##### List the 5 most recent runs: -# List the 5 most recent runs +```bash depot ci run list -n 5 ``` +##### List runs as JSON: + +```bash +depot ci run list --output json +``` + +JSON response: + +```json +[ + { + "run_id": "", + "repo": "depot/demo-app", + "trigger": "push", + "sha": "abc123def456", + "status": "finished", + "created_at": "2026-04-23T14:30:45Z" + } +] +``` + +The `status` field is a string: `queued`, `running`, `finished`, `failed`, or `cancelled`. + +--- + +## `depot ci workflow` + +Manages CI workflows. + +### `depot ci workflow list` + +Lists recent CI workflow runs for your organization. By default returns the 50 most recent. + +```bash +depot ci workflow list +``` + +Alias: `depot ci workflow ls`. + +#### Flags + +| Flag | Description | +| --------------------- | ------------------------------------------------------------------------------------------------- | +| `-n ` | Number of recent workflows to return (default: `50`, max: `200`) | +| `--name ` | Filter by workflow name | +| `--repo ` | Filter by repository in `owner/name` format | +| `--status ` | Filter by status; can be repeated. Values: `queued`, `running`, `finished`, `failed`, `cancelled` | +| `--trigger ` | Filter by trigger event, for example `push` or `workflow_dispatch` | +| `--sha ` | Filter by head SHA prefix | +| `--pr ` | Filter by pull request number | +| `--output json` | Output as JSON instead of a table | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | + +#### Examples + +##### List recent workflows: + +```bash +depot ci workflow list +``` + +##### List the 5 most recent workflows: + +```bash +depot ci workflow list -n 5 +``` + +##### Filter by workflow name: + +```bash +depot ci workflow list --name deploy +``` + +##### Filter workflows by repo, status, and SHA: + +```bash +depot ci workflow list --repo depot/api --status failed --sha abc123 +``` + +##### List workflows as JSON: + +```bash +depot ci workflow list --output json +``` + +JSON response: + +```json +[ + { + "workflow_id": "", + "name": "CI", + "workflow_path": ".depot/workflows/ci.yml", + "repo": "depot/api", + "status": "finished", + "trigger": "push", + "run_id": "", + "sha": "", + "head_sha": "", + "created_at": "2026-04-28T12:00:00Z", + "job_counts": { + "total": 5, + "queued": 0, + "waiting": 0, + "running": 0, + "finished": 5, + "failed": 0, + "cancelled": 0, + "skipped": 0 + } + } +] +``` + +The `status` field is a string: `queued`, `running`, `finished`, `failed`, or `cancelled`. + +--- + +### `depot ci workflow show` + +Shows a CI workflow, including the parent run context, executions, jobs, and per-job attempt details. + +```bash +depot ci workflow show +``` + +Alias: `depot ci workflow get`. + +#### Flags + +| Flag | Description | +| ----------------- | -------------------------------------------------------------------------- | +| `--output json` | Output as JSON instead of a table | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | + +#### Examples + +##### Show a workflow: + +```bash +depot ci workflow show +``` + +The command prints: + +- Org, repo, run ID with status, workflow ID with status, name, path, ref, SHA, and trigger. +- Each execution with its status, start time, finish time, and duration. +- Each job with its status and duration. For each job, the latest attempt's ID, status, sandbox ID, session ID, and a ready-to-run `depot ci logs` command are shown. If the job has more than one attempt, all attempts are listed. + +##### Show a workflow as JSON: + +```bash +depot ci workflow show --output json +``` + +JSON response: + +```json +{ + "org_id": "", + "run": { + "run_id": "", + "repo": "depot/api", + "ref": "refs/heads/main", + "sha": "", + "head_sha": "", + "trigger": "push", + "status": "failed", + "created_at": "2026-04-30T14:01:00Z", + "started_at": "2026-04-30T14:02:00Z", + "finished_at": "2026-04-30T14:25:15Z" + }, + "workflow": { + "workflow_id": "", + "name": "CI", + "workflow_path": ".depot/workflows/ci.yml", + "status": "failed", + "error_message": "tests failed", + "created_at": "2026-04-30T14:01:05Z", + "started_at": "2026-04-30T14:02:11Z", + "finished_at": "2026-04-30T14:25:15Z" + }, + "executions": [...], + "jobs": [...] +} +``` + +--- + +## `depot ci dispatch` + +Triggers a workflow via `workflow_dispatch`. Inputs are validated against the workflow's declared input schema, so required inputs must be supplied and typed inputs (`boolean`, `number`, `choice`) are coerced on the server. + +```bash +depot ci dispatch --repo --workflow --ref +``` + +**Note**: `--workflow` takes the workflow file's basename (for example `deploy.yml`), not the full repo path `.depot/workflows/deploy.yml`. + +### Flags + +| Flag | Description | +| ----------------------- | ------------------------------------------------------------------------------ | +| `--repo ` | Target GitHub repository (required) | +| `--workflow ` | Workflow file basename (required), for example `deploy.yml`, not the full path | +| `--ref ` | Branch or tag name to run the workflow on (required) | +| `--input =` | Workflow input as `key=value`; repeat for multiple inputs | +| `--output json` | Output the RPC response as JSON | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | + +### Examples + +#### Dispatch a workflow on the main branch + +```bash +depot ci dispatch --repo depot/demo-app --workflow deploy.yml --ref main +``` + +```bash +depot ci dispatch --repo depot/demo-app --workflow deploy.yml --ref main --output json +``` + +JSON response: + +```json +{ + "org_id": "", + "run_id": "" +} +``` + +#### Pass inputs + +```bash +depot ci dispatch --repo depot/demo-app --workflow deploy.yml --ref main \ + --input environment=staging --input dry_run=true +``` + --- ## `depot ci status` @@ -239,6 +509,199 @@ Replace `` with the run ID returned by `depot ci run` or visible in the --- +## `depot ci cancel` + +Cancels a queued or running workflow (all its jobs), or a single job within a workflow. + +```bash +depot ci cancel --workflow +depot ci cancel --job +``` + +Exactly one of `--workflow` or `--job` must be provided; they are mutually exclusive. When you pass `--job`, the CLI looks up the containing workflow via the run's status, so you do not need to also pass `--workflow`. + +Workflows and jobs that have already reached a terminal state (finished, failed, or cancelled) cannot be cancelled and will return an error. + +### Flags + +| Flag | Description | +| ----------------- | -------------------------------------------------------------------------- | +| `--workflow ` | Workflow ID to cancel (mutually exclusive with `--job`) | +| `--job ` | Job ID to cancel (mutually exclusive with `--workflow`) | +| `--output json` | Output the RPC response as JSON | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | + +### Examples + +#### Cancel an entire workflow (all jobs within it) + +```bash +depot ci cancel --workflow +``` + +```bash +depot ci cancel --workflow --output json +``` + +JSON response: + +```json +{"workflow_id": "", "status": "cancelled"} +``` + +#### Cancel a single job (workflow is resolved automatically) + +```bash +depot ci cancel --job +``` + +```bash +depot ci cancel --job --output json +``` + +JSON response: + +```json +{"job_id": "", "status": "cancelled"} +``` + +--- + +## `depot ci rerun` + +Re-runs every job in a workflow that has reached a terminal state. Creates a new attempt for each job. + +```bash +depot ci rerun +``` + +If the run contains multiple workflows, pass `--workflow ` to select one. When the run contains a single workflow, the CLI resolves it automatically. Rerunning a workflow that is still running returns a precondition error — cancel it first if you want to restart. + +### Flags + +| Flag | Description | +| ----------------- | -------------------------------------------------------------------------- | +| `--workflow ` | Workflow ID to rerun (required when the run contains multiple workflows) | +| `--output json` | Output the RPC response as JSON | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | + +### Examples + +#### Rerun the workflow in a run + +```bash +depot ci rerun +``` + +```bash +depot ci rerun --output json +``` + +JSON response: + +```json +{"workflow_id": "", "job_count": 5} +``` + +#### Rerun a specific workflow in a multi-workflow run + +```bash +depot ci rerun --workflow +``` + +```bash +depot ci rerun --workflow --output json +``` + +JSON response: + +```json +{"workflow_id": "", "job_count": 5} +``` + +--- + +## `depot ci retry` + +Retries a single failed or cancelled job, or every failed and cancelled job in a workflow. + +```bash +depot ci retry --job +depot ci retry --failed +``` + +Requires exactly one of `--job` or `--failed`. + +- `--job ` retries a single job. The workflow containing the job is resolved automatically from the run's status. +- `--failed` retries every failed/cancelled job in the workflow. If the run contains multiple workflows, pass `--workflow `; otherwise the single workflow is resolved automatically. + +Each retry creates a new attempt for the selected job(s); the previous attempts are preserved and visible in `depot ci status`. + +### Flags + +| Flag | Description | +| ----------------- | ---------------------------------------------------------------------------------- | +| `--job ` | Job ID to retry (mutually exclusive with `--failed`) | +| `--failed` | Retry every failed/cancelled job in the workflow (mutually exclusive with `--job`) | +| `--workflow ` | Workflow ID; required with `--failed` when the run has multiple workflows | +| `--output json` | Output the RPC response as JSON | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | + +### Examples + +#### Retry a single job + +```bash +depot ci retry --job +``` + +```bash +depot ci retry --job --output json +``` + +JSON response: + +```json +{"job_id": "", "attempt_id": "", "attempt": 2, "status": "queued"} +``` + +#### Retry every failed and cancelled job in the only workflow + +```bash +depot ci retry --failed +``` + +```bash +depot ci retry --failed --output json +``` + +JSON response: + +```json +{"workflow_id": "", "job_ids": ["", "..."], "job_count": 3} +``` + +#### Retry every failed and cancelled job in a specific workflow + +```bash +depot ci retry --failed --workflow +``` + +```bash +depot ci retry --failed --workflow --output json +``` + +JSON response: + +```json +{"workflow_id": "", "job_ids": ["", "..."], "job_count": 3} +``` + +--- + ## `depot ci logs` Fetches and prints the log output for a CI job. Accepts a run ID, job ID, or attempt ID. When given a run or job ID, the command resolves to the latest attempt automatically. Use `--job` and `--workflow` to disambiguate when a run has multiple jobs. @@ -258,17 +721,27 @@ depot ci logs ### Examples +#### Fetch logs by attempt ID + ```bash -# Fetch logs by attempt ID depot ci logs +``` + +#### Fetch logs for the latest attempt of a run -# Fetch logs for the latest attempt of a run (single-job workflow) +```bash depot ci logs +``` + +#### Fetch logs for a specific job in a run -# Fetch logs for a specific job in a run +```bash depot ci logs --job test +``` + +#### Disambiguate when job names overlap across workflows -# Disambiguate with workflow path when job names overlap across workflows +```bash depot ci logs --job build --workflow ci.yml ``` @@ -294,20 +767,39 @@ depot ci ssh ### Examples +#### Connect to a job by job ID + ```bash -# Connect to a job by job ID depot ci ssh +``` + +#### Connect to a specific job in a run -# Connect to a specific job in a run +```bash depot ci ssh --job build +``` -# Print SSH connection details without connecting +#### Print SSH connection details without connecting + +```bash depot ci ssh --info +``` -# Print SSH connection details as JSON +```bash depot ci ssh --info --output json ``` +JSON response: + +```json +{ + "host": "api.depot.dev", + "sandbox_id": "", + "session_id": "", + "ssh_command": "ssh @api.depot.dev" +} +``` + --- ## `depot ci secrets` @@ -322,9 +814,9 @@ depot ci secrets add SECRET_NAME Supports three modes: -- **Single secret with prompt**: `depot ci secrets add SECRET_NAME` — omit `--value` and the CLI prompts you to enter the value securely (input is hidden). -- **Single secret with flag**: `depot ci secrets add SECRET_NAME --value "val"` -- **Bulk KEY=VALUE pairs**: `depot ci secrets add FOO=bar BAZ=qux` — sets multiple secrets in one command. The `--value` and `--description` flags cannot be used in this mode. +- Single secret with prompt: `depot ci secrets add SECRET_NAME` — omit `--value` and the CLI prompts you to enter the value securely (input is hidden). +- Single secret with flag: `depot ci secrets add SECRET_NAME --value "val"` +- Bulk KEY=VALUE pairs: `depot ci secrets add FOO=bar BAZ=qux` — sets multiple secrets in one command. The `--value` and `--description` flags cannot be used in this mode. | Flag | Description | | ---------------------- | ------------------------------------------------------------------------------------ | @@ -334,6 +826,38 @@ Supports three modes: | `--org ` | Organization ID | | `--token ` | Depot API token | +#### Examples + +##### Add an org-wide secret (prompts for value): + +```bash +depot ci secrets add MY_API_KEY +``` + +##### Add an org-wide secret with value inline: + +```bash +depot ci secrets add MY_API_KEY --value "secret-value" +``` + +##### Add a secret with a description: + +```bash +depot ci secrets add MY_API_KEY --value "secret-value" --description "API key for payment provider" +``` + +##### Add multiple secrets using KEY=VALUE pairs: + +```bash +depot ci secrets add GITHUB_TOKEN=ghp_xxx MY_API_KEY=secret-value +``` + +##### Add a repo-scoped secret: + +```bash +depot ci secrets add DATABASE_URL --repo owner/repo --value "postgres://..." +``` + ### `depot ci secrets list` ```bash @@ -349,6 +873,20 @@ Displays names and metadata (no values) for all secrets configured for your orga | `--org ` | Organization ID | | `--token ` | Depot API token | +#### Examples + +##### List org-wide secrets: + +```bash +depot ci secrets list +``` + +##### List org-wide and repo-scoped secrets together: + +```bash +depot ci secrets list --repo owner/repo +``` + ### `depot ci secrets remove` ```bash @@ -357,27 +895,39 @@ depot ci secrets remove SECRET_NAME [SECRET_NAME...] Alias: `depot ci secrets rm`. Accepts one or more secret names. Prompts for confirmation before deleting. +| Flag | Description | +| --------------------- | ------------------------------------------------------------ | +| `--repo ` | Remove a repo-specific secret instead of the org-wide secret | +| `--force` | Skip confirmation prompt | +| `--org ` | Organization ID | +| `--token ` | Depot API token | + +#### Examples + +##### Remove a single secret: + ```bash -# Remove a single secret depot ci secrets remove MY_API_KEY +``` + +##### Remove a repo-specific secret: -# Remove a repo-specific secret +```bash depot ci secrets remove MY_API_KEY --repo owner/repo +``` + +##### Remove multiple secrets at once: -# Remove multiple secrets at once +```bash depot ci secrets remove GITHUB_TOKEN MY_API_KEY DATABASE_URL +``` + +##### Remove a secret without confirmation: -# Remove without confirmation +```bash depot ci secrets remove GITHUB_TOKEN MY_API_KEY --force ``` -| Flag | Description | -| --------------------- | ------------------------------------------------------------ | -| `--repo ` | Remove a repo-specific secret instead of the org-wide secret | -| `--force` | Skip confirmation prompt | -| `--org ` | Organization ID | -| `--token ` | Depot API token | - --- ## `depot ci vars` @@ -392,9 +942,9 @@ depot ci vars add VAR_NAME --value "some-value" Supports three modes: -- **Single variable with prompt**: `depot ci vars add VAR_NAME` — omit `--value` and the CLI prompts you to enter the value. -- **Single variable with flag**: `depot ci vars add VAR_NAME --value "val"` -- **Bulk KEY=VALUE pairs**: `depot ci vars add FOO=bar BAZ=qux` — sets multiple variables in one command. The `--value` flag cannot be used in this mode. +- Single variable with prompt: `depot ci vars add VAR_NAME` — omit `--value` and the CLI prompts you to enter the value. +- Single variable with flag: `depot ci vars add VAR_NAME --value "val"` +- Bulk KEY=VALUE pairs: `depot ci vars add FOO=bar BAZ=qux` — sets multiple variables in one command. The `--value` flag cannot be used in this mode. | Flag | Description | | --------------------- | ---------------------------------------------------------------------------------------- | @@ -403,6 +953,32 @@ Supports three modes: | `--org ` | Organization ID | | `--token ` | Depot API token | +#### Examples + +##### Add an org-wide variable (prompts for value): + +```bash +depot ci vars add SERVICE_NAME +``` + +##### Add an org-wide variable with value inline: + +```bash +depot ci vars add SERVICE_NAME --value "api" +``` + +##### Add multiple variables using KEY=VALUE pairs: + +```bash +depot ci vars add REGION=us-east-1 ENV=prod +``` + +##### Add a repo-scoped variable: + +```bash +depot ci vars add DEPLOY_ENV --repo owner/repo --value "production" +``` + ### `depot ci vars list` ```bash @@ -418,6 +994,20 @@ Use `--repo` to also show repo-specific variables that override org-wide values. | `--org ` | Organization ID | | `--token ` | Depot API token | +#### Examples + +##### List org-wide variables: + +```bash +depot ci vars list +``` + +##### List org-wide and repo-scoped variables together: + +```bash +depot ci vars list --repo owner/repo +``` + ### `depot ci vars remove` ```bash @@ -426,23 +1016,35 @@ depot ci vars remove VAR_NAME [VAR_NAME...] Alias: `depot ci vars rm`. Accepts one or more variable names. Prompts for confirmation before deleting. +| Flag | Description | +| --------------------- | ---------------------------------------------------------------- | +| `--repo ` | Remove a repo-specific variable instead of the org-wide variable | +| `--force` | Skip confirmation prompt | +| `--org ` | Organization ID | +| `--token ` | Depot API token | + +#### Examples + +##### Remove a single variable: + ```bash -# Remove a single variable depot ci vars remove GITHUB_REPO +``` + +##### Remove a repo-specific variable: -# Remove a repo-specific variable +```bash depot ci vars remove GITHUB_REPO --repo owner/repo +``` + +##### Remove multiple variables at once: -# Remove multiple variables at once +```bash depot ci vars remove GITHUB_REPO MY_SERVICE_NAME DEPLOY_ENV +``` + +##### Remove a variable without confirmation: -# Remove without confirmation +```bash depot ci vars remove GITHUB_REPO MY_SERVICE_NAME --force ``` - -| Flag | Description | -| --------------------- | ---------------------------------------------------------------- | -| `--repo ` | Remove a repo-specific variable instead of the org-wide variable | -| `--force` | Skip confirmation prompt | -| `--org ` | Organization ID | -| `--token ` | Depot API token | diff --git a/content/github-actions/integrations/dagger.mdx b/content/github-actions/integrations/dagger.mdx index a834bb2..6389012 100644 --- a/content/github-actions/integrations/dagger.mdx +++ b/content/github-actions/integrations/dagger.mdx @@ -4,6 +4,13 @@ ogTitle: Run your Dagger Engine builds with Depot Runners for GitHub Actions. description: Accelerate your Dagger Engine builds with Depot Runners --- +import {NoteCallout} from '~/components/blog/NoteCallout' + + + Dagger Engine support on Depot GitHub Actions Runners is deprecated and will be removed in a future update. If you are + currently using this integration, please [contact support](/help) for guidance. + + Connect with Dagger Cloud and run your Dagger Engine builds on Depot's [Ultra Runners for GitHub Actions](/products/github-actions) with our accelerated cache enabled. ## Authentication diff --git a/content/integrations/tailscale.mdx b/content/integrations/tailscale.mdx index b7ed0ad..da3791a 100644 --- a/content/integrations/tailscale.mdx +++ b/content/integrations/tailscale.mdx @@ -10,6 +10,8 @@ By connecting Depot to your Tailscale network, you can enable secure access to p Using Tailscale, Depot GitHub Actions runners and container builders join your tailnet as [ephemeral nodes](https://tailscale.com/kb/1111/ephemeral-nodes), and you can control their access to the rest of your infrastructure using Tailscale ACLs. +**Note**: Tailscale integration with Depot Windows runners is not supported. + ## Connecting Depot to your tailnet Connecting your Depot organization to a Tailscale tailnet is a three-step process: diff --git a/content/registry/overview.mdx b/content/registry/overview.mdx index 0d6b864..dc3e260 100644 --- a/content/registry/overview.mdx +++ b/content/registry/overview.mdx @@ -8,7 +8,7 @@ The **Depot Registry** is an OCI-compliant container registry for storing, manag See the [quickstart](/docs/registry/quickstart) to get started. -## How does it work? +## How it works Each Depot organization gets its own registry subdomain: @@ -36,27 +36,33 @@ The [Registry Explorer](/orgs/_/registry/explorer) in the Depot dashboard lets y [![Screenshot showing the Depot Registry Explorer with searchable repositories and tag browsing](/images/docs/registry-page.webp)](/images/docs/registry-page.webp) -## Use-cases +## Use cases -Depot Registry works for a variety of use-cases: +Depot Registry works for a variety of use cases: -- **Primary registry**: Use Depot Registry as your primary container registry for all your images, including ones you're not building with Depot. -- **Ephemeral build store**: Automatically save build output during `depot build --save` and pull it down wherever you need it. -- **Local development**: Pull images directly to your local machine for testing and development. The global CDN ensures fast downloads regardless of your location. -- **Cross-environment consistency**: Build an image once on Depot, save it to the registry, then promote that same image across development, staging, and production without rebuilding. -- **OCI artifacts**: Store any OCI-compliant artifact, including Helm charts and AI models, not just container images. -- **Depot CI custom images**: Snapshot a Depot CI sandbox with your tools and dependencies pre-installed and store it in the registry. Jobs that use the snapshot skip setup entirely, speeding up your CI. See [Build and use custom images](/docs/ci/how-to-guides/custom-images). -- **Working with large images**: The global distribution mechanism makes pulling and pushing large images fast. The registry supports artifacts up to 50GB. +**Primary registry**: Use Depot Registry as your primary container registry for all your images, including ones you're not building with Depot. + +**Ephemeral build store**: Automatically save build output during `depot build --save` and pull it down wherever you need it. + +**Local development**: Pull images directly to your local machine for testing and development. The global CDN ensures fast downloads regardless of your location. + +**Cross-environment consistency**: Build an image once on Depot, save it to the registry, then promote that same image across development, staging, and production without rebuilding. + +**OCI artifacts**: Store any OCI-compliant artifact, including Helm charts and AI models, not just container images. + +**Depot CI custom images**: Snapshot a Depot CI sandbox with your tools and dependencies pre-installed and store it in the registry. Jobs that use the snapshot skip setup entirely, speeding up your CI. See [Build and use custom images](/docs/ci/how-to-guides/custom-images). + +**Working with large images**: The global distribution mechanism makes pulling and pushing large images fast. The registry supports artifacts up to 50GB. ## Pull-through cache -Depot Registry can act as a pull-through cache in front of an existing registry. You configure an upstream registry on a per-repository basis from the repository's settings in the [Registry Explorer](/orgs/_/registry/explorer). Supported authentication methods are basic auth (username and password) and AWS ECR via IAM role ARN for cross-account access. +Depot Registry can proxy pulls from an external registry, caching layers on its CDN so subsequent pulls skip the external hop entirely. Common uses include accelerating CI image pulls, distributing images globally without managing your own CDN, and simplifying access to registries with complex authentication (like Google Artifact Registry). -Once configured, Depot serves pulls from your repository through a global CDN rather than going directly to the upstream, which reduces latency and improves consistency across your infrastructure. +For configuration details and supported providers, see [Pull-through cache](/docs/registry/pull-through-cache). ## Authentication and permissions -Depot Registry authenticates with the same token types used across the rest of the Depot platform. All token types provide both push and pull access except pull tokens, which are read-only: +Depot Registry authenticates with the same token types used across the rest of the Depot platform. All token types provide both push and pull access except for pull tokens, which are read-only. You can use the following types of tokens for registry authentication: - **User access tokens**: Full push and pull permissions for any project in any organization you have access to - **Project tokens**: Full push and pull permissions for the specific project they're associated with @@ -64,7 +70,7 @@ Depot Registry authenticates with the same token types used across the rest of t - **Trust relationship tokens**: Full push and pull permissions for the project when issued via OIDC trust relationships - **Pull tokens**: Read-only, short-lived access for pulling images only (generated via `depot pull-token --project `) -### Authentication for the `docker` CLI +### Authentication for the Docker CLI To use Depot Registry with Docker CLI tools, authenticate using a Depot token. Set the username to `x-token` and the password to your chosen token: diff --git a/content/registry/pull-through-cache.mdx b/content/registry/pull-through-cache.mdx new file mode 100644 index 0000000..a2470e7 --- /dev/null +++ b/content/registry/pull-through-cache.mdx @@ -0,0 +1,73 @@ +--- +title: Pull-through cache +ogTitle: Pull-through cache in Depot Registry +description: Configure Depot Registry as a pull-through cache in front of an external registry to speed up CI, distribute images globally, and simplify private registry access. +--- + +Depot Registry can proxy pulls from an upstream registry. When a pull comes in for a repository with pull-through cache configured, Depot fetches images from the upstream repository, caches them locally to speed up your runners, and serves them through Depot's accelerated CDN. + +Configuration happens in two steps: + +- **Upstream registry**: The external registry connection, including the URL and credentials. You configure upstream registries at the organization level and they can be reused across multiple Depot repositories. +- **Upstream repository**: The image path within an upstream registry that a Depot repository mirrors. You choose this path when creating a Depot repository. + +You can create and update upstream registries from [Registry Settings](/orgs/_/registry/settings). Pull-through cache for an individual repository can only be configured when you cerate the repository. + +## Use cases + +**Faster CI pulls**: Pulling images from Docker Hub or another external registry in CI can take several minutes per job. It's also subject to rate limits and upstream availability. With pull-through cache configured, Depot serves cached layers from its CDN rather than the upstream source, so the pull is fast and doesn't depend on an external service being up. + +**Global image distribution**: Depot's CDN distributes cached layers globally. If you're running jobs or deployments across multiple regions, configuring your registry as an upstream means every region pulls from a nearby CDN node rather than a single-region origin. + +**Simplified private registry access**: Some registries, like Google Artifact Registry and Google Container Registry, require OAuth-based service account credentials that are complex to configure in every environment. With Depot, you enter the upstream registry's credentials once in the dashboard, and Depot handles authentication to the upstream on every pull. A client needs only a Depot token to pull images. + +## Configure an upstream registry + +Manage upstream registries from the **Registry settings**. Adding an upstream registry here lets you reuse the same credentials across multiple Depot repositories. + +1. Open [Registry Settings](/orgs/_/registry/settings) in the Depot dashboard. +2. Under **Pull-through cache**, click **Add upstream registry**. +3. Select a provider from the dropdown. +4. Fill in the registry URL and credentials for the provider (see [Supported registries](#supported-registries)). +5. Click **Save upstream registry**. + +Once saved, the upstream registry appears in the list and is available when creating a pull-through repository. You can create the repository from Registry Settings by clicking **Create pull-through repository** on the upstream registry, or create it from the repository creation page and select the upstream registry there. + +## Create a pull-through repository + +After creating an upstream registry, create a Depot repository and configure pull-through cache during repository creation. + +1. Open [Repositories](/orgs/_/registry/repositories) in the Depot dashboard. +2. Click **Create repository**. +3. Enter the Depot repository name. +4. Under **Pull-through cache**, click **Configure**. +5. Select **Existing registry** and choose the upstream registry from the dropdown. If you haven't created one yet, select **New registry** to create one inline. +6. Enter the upstream repository path to mirror. +7. Click **Create repository**. + +Once created, Depot proxies pulls from that Depot repository through the configured upstream repository. If Depot previously cached the requested layer, it serves the layer from the CDN without contacting the upstream registry. + +The first pull of an image can be slower because Depot needs to fetch the manifest and missing blobs from the upstream registry. Subsequent pulls are served from Depot while those blobs remain cached. Pull-through blobs that aren't referenced by a pushed manifest become eligible for cleanup after 6 hours without repository access; once they are cleaned up, the next pull fetches them from the upstream registry again. + +Pull-through cache cannot be added to or changed for an existing repository. If you need a different upstream repository, create a new Depot repository with the desired pull-through cache configuration. + +To pull images through Depot Registry, use a [pull token](/docs/cli/authentication#pull-tokens) rather than the upstream registry's credentials. + +## Supported registries + +| Registry | URL | Auth method | +| ------------------------- | -------------------------------------------- | ------------------------------------------------------ | +| Docker Hub | `https://registry-1.docker.io` | Basic auth: Docker Hub username + access token | +| GitHub Container Registry | `https://ghcr.io` | Basic auth: GitHub username + personal access token | +| GitLab Container Registry | `https://registry.gitlab.com` | Basic auth: GitLab username + personal access token | +| Quay.io | `https://quay.io` | Basic auth: Quay.io username + password or robot token | +| AWS ECR | Your ECR registry URL | IAM role ARN | +| Google Artifact Registry | `https://us-docker.pkg.dev` (or your region) | Basic auth: `_json_key` + service account JSON key | +| Azure Container Registry | Your ACR URL | Basic auth: service principal client ID + secret | +| Custom registry | Your registry URL | Basic auth: username + password | + +Credentials are required for Docker Hub and for any private repository. For other registries, you can omit credentials if the upstream repository is public. + +### AWS ECR authentication + +For AWS ECR upstreams, Depot authenticates using an IAM role ARN rather than static credentials. Enter the ARN of a role that grants Depot read access to your ECR registry. Contact [support@depot.dev](mailto:support@depot.dev) for the trust relationship configuration details needed to allow Depot to assume the role.