From f306d826c41e46bfa6aa2a846f2ee373eb53cccf Mon Sep 17 00:00:00 2001 From: andie787 <13827355+andie787@users.noreply.github.com> Date: Mon, 11 May 2026 21:24:42 +0000 Subject: [PATCH] Update docs content from https://github.com/depot/app --- content/ci/how-to-guides/custom-images.mdx | 8 +- .../manage-secrets-and-variables.mdx | 135 ++--- content/cli/reference/depot-ci.mdx | 176 ++++++- .../how-to-guides/continuous-integration.mdx | 1 + .../integrations/depot-ci.mdx | 462 ++++++++++++++++++ .../integrations/github-actions.mdx | 5 +- content/container-builds/quickstart.mdx | 1 + content/github-actions/troubleshooting.mdx | 2 +- 8 files changed, 695 insertions(+), 95 deletions(-) create mode 100644 content/container-builds/integrations/depot-ci.mdx diff --git a/content/ci/how-to-guides/custom-images.mdx b/content/ci/how-to-guides/custom-images.mdx index 0b85831..e875185 100644 --- a/content/ci/how-to-guides/custom-images.mdx +++ b/content/ci/how-to-guides/custom-images.mdx @@ -10,7 +10,7 @@ Build a reusable custom image from the Depot base image that includes your tools ## How it works -You build a custom image in Depot CI using a job that runs only your setup steps on the Depot base image. After your setup steps complete, a Depot snapshot action captures the state of the sandbox environment and pushes it to the Depot registry as a reusable image. Any job can then use that snapshot as its starting image, skipping the setup steps entirely. +A custom image in Depot CI is a snapshot of a sandbox environment. You build the custom image using a job that runs only your setup steps on the Depot base image. After your setup steps complete, a Depot snapshot action captures the state of the sandbox environment and pushes it to the Depot registry as a reusable image. Any job can then use that snapshot as its starting image, skipping the setup steps entirely. The snapshot action can only be used in workflows running on Depot CI. It's not compatible with GitHub Actions or @@ -19,7 +19,7 @@ You build a custom image in Depot CI using a job that runs only your setup steps ## Snapshot a sandbox to build a custom image -Create a job that runs on a standard Depot sandbox and installs the tools and dependencies you want to bake in. This is a separate workflow that only creates your custom image and pushes it to the Depot Registry. You'll need to run this workflow initially to create the image and then only when dependencies change. +Build a custom image using a job that runs on a standard Depot sandbox and installs the tools and dependencies you want to bake in. The job creates your custom image and pushes it to the Depot Registry. Use a separate workflow for the build image job, and then use the resulting image in one or more other workflows. This pattern is usually the most efficient because you run the image build workflow once to create the image and then only when dependencies change. If your use case differs, you can also run the build image job in the same workflow as other jobs that subsequently use it. Actions that set or change environment variables (such as actions/setup-node) need to be in both the build image @@ -63,7 +63,9 @@ Any job in any workflow on Depot CI can specify your custom image. The custom im To run a job on a custom image, specify `runs-on` with `size` and `image` keys (both required). - `size`: the size of the sandbox -- `image`: is the Depot registry URL you specified in the build image workflow +- `image`: the Depot registry URL of the image (defined in the build image workflow) + +The `runs-on.image` value must be a Depot registry URL for an image created using the `depot/snapshot-action` as described in [Snapshot a sandbox to build a custom image](#snapshot-a-sandbox-to-build-a-custom-image). You can't use any other images or artifacts, even if they exist in the Depot registry. Example specifying a custom image in a job: 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 194a929..1c62b35 100644 --- a/content/ci/how-to-guides/manage-secrets-and-variables.mdx +++ b/content/ci/how-to-guides/manage-secrets-and-variables.mdx @@ -6,13 +6,13 @@ description: Learn how to add and remove secrets and environment variables for u 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 manage secrets and variables from the [Depot CI Settings](https://depot.dev/orgs/_/workflows/settings) in the dashboard or from the CLI. +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, a repository-scoped secret is available only to jobs running for that repository. When multiple secrets have the same name, Depot chooses +Within an organization, a secret scoped to a repository 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). @@ -29,13 +29,11 @@ This creates a one-shot GitHub Actions workflow that reads secrets and variables ## Manage secrets -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. +You need to be an [organization owner](/docs/account#organization-access-roles) to manage 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. -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. +Use the dashboard to create secrets and variables and optionally limit availability by repository, branch, workflow, or environment. You can also add and remove secrets and variables using the [Depot CLI](/docs/cli/reference/depot-ci). -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 (`/`). +Names must be non-empty and names matching to a specific repository can't contain a forward slash (`/`). ### Add a secret @@ -43,7 +41,9 @@ Names must be non-empty and repository-scoped names can't contain a forward slas 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. +5. Optional: **Limit availability** by defining when to use the secret. Learn more about [limiting availability](#limit-availability-of-secrets-and-variables). + 1. Define a single attribute or any combination of repository, branch, workflow, and environment attributes. + 2. Enter a **Variant name**, or keep the auto-generated name. 6. Click **Create secret**. ### Add a variable @@ -52,58 +52,61 @@ Names must be non-empty and repository-scoped names can't contain a forward slas 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. +5. Optional: **Limit availability** by defining when to use the variable. Learn more about [limiting availability](#limit-availability-of-secrets-and-variables). + 1. Define a single attribute or any combination of repository, branch, workflow, and environment attributes. + 2. Enter a **Variant name**, or keep the auto-generated name. 6. Click **Create variable**. ### Update secrets and variables You can update a secret or variable's description, value, and availability from 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't view secret values after you create a secret, so you can only enter a new value. 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**. +3. Find the secret or variable you want to edit. +4. Click the variant name or the details icon to open the details panel. +5. In the details panel, click the edit icon. +6. Update the fields and click **Save changes**. ### Remove secrets and variables 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**. +3. Find the secret or variable you want to remove. +4. Click the variant name or the details icon to open the details panel. +5. In the details panel, click the trash icon and then click **Delete** to confirm. ## Limit availability of secrets and variables 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. -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 example, a deployment key in an open source repository might be needed only 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. -Limit availability using one or more kinds of rule: +Limit availability using one or more of the following attributes: - **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. -Both branch and workflow rules support glob patterns. For example, `release/*` or `deploy-*.yaml`. +Both branch and workflow attributes support glob patterns. For example, `release/*` or `deploy-*.yaml`. -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: +Availability gets stricter when you add different kinds of attributes and broader when you add alternatives within the same kind of attribute. For example, a secret with the following attributes: -- Branch rule main -- Branch rule -- Environment rule production +- Branch main +- Branch +- Environment production is accessible only when the branch matches main _or_ _and_ the `environment` field in the workflow YAML matches production. -### Using environment rules +### Using environment attributes -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 attribute matches to the job's `environment` field in your workflow YAML. Use an environment attribute when a value should be available only to jobs that explicitly run in an environment such as `staging` or `production`. -For example, an environment rule with the value production matches the `deploy` job in the following workflow snippet. +For example, an environment attribute with the value production matches the `deploy` job in the following workflow snippet. ```yaml name: Deploy @@ -133,9 +136,9 @@ jobs: url: https://app.example.com ``` -Depot uses the environment `name` for rule matching. +Depot uses the environment `name` for attribute matching. -Jobs without an `environment` field do not match environment rules, even if they run on the same branch or in the same workflow file. +Jobs without an `environment` field do not match environment attributes, even if they run on the same branch or in the same workflow file. ## Secret and variable variants @@ -144,78 +147,48 @@ Variants let one secret or variable name resolve to different values depending o Use variants when the workflow should receive a different value depending on where it runs. For example, you can create: - A default `DATABASE_URL` secret or variable for all repositories. -- A release `DATABASE_URL` secret or variable selected by a branch rule. +- A release `DATABASE_URL` secret or variable selected by a branch attribute match. - A repository-specific `DATABASE_URL` secret or variable. -- A production `DATABASE_URL` secret or variable selected by an environment rule. - -You can create, view, and manage all of these variants in the dashboard: +- A production `DATABASE_URL` secret or variable selected by an environment attribute match. -![Multiple variants for DATABASE_URL secret in Depot CI](/images/docs/depot-ci-secrets-example.png) - -The dashboard always displays variants sorted from least specific to most specific. +You can create, view, and manage all of these variants in the dashboard. You can also use filters to [check which variant resolves](#check-variant-resolution-in-the-dashboard) for your workflow before running it. ### Add a variant using 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. Click **Add variant**. +3. Click the variant link or the details icon for the secret or variable you want to create a variant from. This opens the details panel. +4. In the details panel, click the plus icon. 5. Enter the new **Value** and optionally update the **Description**. -6. Add rules to limit availability by repository, branch name, workflow file, or environment. +6. Under **Limit availability**, define a single attribute or any combination of repository, branch, workflow, and environment attributes. 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. +Depot resolves matching variants before a workflow starts. A repository 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. +When multiple variants match a job, the variants resolve from least to most specific and with the following priority from highest to lowest: environment, repository, branch, workflow. 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. +| Attribute type | Priority | Resolution | +| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Environment | Highest | Beats repository, branch, and workflow attributes. For example, a variant with only an environment attribute beats a variant with only a repository attribute. | +| Repository | High | Beats branch and workflow attributes. | +| Branch | Medium | Beats workflow attributes. Narrow branch glob patterns beat broad ones. For example, `release/v2` beats `release/*`. | +| Workflow | Low | Narrow workflow file glob patterns beat broad ones. | +| No attributes | Lowest | Matches all jobs (fallback value). | -#### 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. +Combining attribute types always increases specificity. A variant with both an environment and a repository attribute beats a variant with only one of them. So a variant with no repository attribute (matching any repo by default) and a defined environment attribute beats a variant with a repository attribute and no environment attribute. To resolve to a different value for a specific repo, create a variant that matches to both the repository and the environment. -## Bulk changes to secrets and variables +#### Check variant resolution in the dashboard -Select multiple secrets or variables to delete them or update their availability rules at once. +You can use the filter to confirm which variant resolves to your workflow before running it. With no filters applied, the dashboard displays variants for each secret sorted from least specific to most specific. -### Bulk delete secrets or variables +1. From the [Depot CI workflows](/orgs/_/workflows) page, click **Secrets** or **Variables**. +2. Click the filter icon beside the search bar. +3. In the filter context panel, select **Env**, **Repo**, **Branch**, or **Workflow** to view defined attributes for each across your organization. +4. Click the attributes that match the workflow you want to check to filter the workflow view. -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**. + When a variant is the definitive winner for a specific secret or variable, it moves to the top of the list and the other variants are greyed out. diff --git a/content/cli/reference/depot-ci.mdx b/content/cli/reference/depot-ci.mdx index ebd1379..ed978fd 100644 --- a/content/cli/reference/depot-ci.mdx +++ b/content/cli/reference/depot-ci.mdx @@ -391,7 +391,7 @@ 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. +- Each job with its status and duration. For each job, the command shows the latest attempt's ID, status, sandbox ID, session ID, and a ready-to-run `depot ci logs` command. If the job has more than one attempt, all attempts are listed. ##### Show a workflow as JSON: @@ -498,15 +498,65 @@ Replace `` with the run ID returned by `depot ci run` or visible in the - The organization and run ID with the overall run status. - Each workflow in the run, with its status and workflow file path. - Each job within a workflow, with its job ID, key, and status. -- Each attempt within a job, with its attempt ID, attempt number, and status. +- Each attempt within a job, with its attempt ID, attempt number, and status. Plus a ready-to-run `depot ci logs` command, a link to the attempt in the Depot dashboard, and (when applicable) `depot ci ssh` and log download commands. ### Flags | Flag | Description | | ----------------- | -------------------------------------------------------------------------- | +| `--output json` | Output as JSON instead of the hierarchical text view | | `--org ` | Organization ID (required when user is a member of multiple organizations) | | `--token ` | Depot API token | +### Examples + +#### Show the status as JSON + +```bash +depot ci status --output json +``` + +JSON response: + +```json +{ + "org_id": "", + "run_id": "", + "status": "running", + "workflows": [ + { + "workflow_id": "", + "status": "running", + "workflow_path": ".depot/workflows/ci.yml", + "name": "CI", + "jobs": [ + { + "job_id": "", + "job_key": "ci.yml:test", + "status": "running", + "attempts": [ + { + "attempt_id": "", + "attempt": 1, + "status": "running", + "sandbox_id": "", + "session_id": "", + "logs_command": "depot ci logs ", + "download_available": false, + "view_url": "https://depot.dev/orgs//workflows/?job=&attempt=", + "ssh_available": true, + "ssh_command": "depot ci ssh --job ci.yml:test" + } + ] + } + ] + } + ] +} +``` + +`download_available` becomes `true` and `download_command` appears once the attempt reaches `finished` status. `ssh_available` and `ssh_command` appear only while the attempt is running with a sandbox. + --- ## `depot ci cancel` @@ -712,12 +762,16 @@ depot ci logs ### Flags -| Flag | Description | -| ------------------- | -------------------------------------------------------------------------- | -| `--job ` | Job key to select (required when the run has multiple jobs) | -| `--workflow ` | Workflow path to filter jobs (for example, `ci.yml`) | -| `--org ` | Organization ID (required when user is a member of multiple organizations) | -| `--token ` | Depot API token | +| Flag | Description | +| ---------------------- | -------------------------------------------------------------------------- | +| `--job ` | Job key to select (required when the run has multiple jobs) | +| `--workflow ` | Workflow path to filter jobs (for example, `ci.yml`) | +| `--follow`, `-f` | Follow live logs as they're produced | +| `--timestamps` | Prefix plain log lines with UTC timestamps | +| `--output ` | Output format: `text` (default) or `json` (newline-delimited events) | +| `--output-file ` | Write a finite log export to the given file path | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | ### Examples @@ -745,6 +799,112 @@ depot ci logs --job test depot ci logs --job build --workflow ci.yml ``` +#### Follow live logs + +```bash +depot ci logs --follow +``` + +If you pass a run or job ID that hasn't started yet, the command waits up to 30 seconds for the run to create jobs and start the latest attempt, then streams logs as they arrive. + +#### Prefix log lines with UTC timestamps + +```bash +depot ci logs --timestamps +``` + +#### Emit logs as newline-delimited JSON events + +```bash +depot ci logs --output json +``` + +The finite form emits one `line` event per log line, with `timestamp`, `timestamp_ms`, `stream` (`stdout` or `stderr`), `step_key`, `step_id`, `step_name`, `line_number`, and `body`. + +Combine with `--follow` to stream the live attempt as JSON. The streaming form emits the same `line` events plus two additional event types: + +```bash +depot ci logs --follow --output json +``` + +- `status`: signals an attempt status change (for example, `running`, `finished`, `failed`). +- `end`: marks the end of the stream, with the final `status` and `line_count`. + +#### Download logs to a file + +```bash +depot ci logs --output-file logs.txt +``` + +Use `--output-file` together with `--output json` to download a JSONL export: + +```bash +depot ci logs --output json --output-file logs.jsonl +``` + +`--output-file` doesn't work with `--follow`. + +--- + +## `depot ci metrics` + +Fetches CPU and memory metrics for a CI job attempt, job, or run. + +```bash +depot ci metrics +``` + +When given an attempt ID, the command prints a summary of CPU and memory utilization for that attempt. To inspect every attempt of a job or every job in a run, pass `--job ` or `--run ` instead. The positional attempt ID and the `--attempt`, `--job`, and `--run` flags are mutually exclusive. + +For full per-sample CPU and memory readings on a single attempt, add `--output json`. Job and run requests return per-attempt summary stats (no per-sample `samples` array) even with `--output json`. + +### Flags + +| Flag | Description | +| ------------------------ | -------------------------------------------------------------------------- | +| `--attempt ` | Job attempt ID (alias for the positional argument) | +| `--job ` | Show metrics for every attempt of the given job | +| `--run ` | Show metrics for every job and attempt in the given run | +| `--output ` | Output format: `text` (default) or `json` | +| `--org ` | Organization ID (required when user is a member of multiple organizations) | +| `--token ` | Depot API token | + +### Examples + +#### Show metrics for an attempt + +```bash +depot ci metrics +``` + +#### Show metrics for every attempt of a job + +```bash +depot ci metrics --job +``` + +#### Show metrics for every job in a run + +```bash +depot ci metrics --run +``` + +#### Show full per-sample metrics as JSON + +```bash +depot ci metrics --output json +``` + +The JSON response describes the attempt's availability, summary stats (peak and average CPU and memory utilization, sample counts, observed start and finish times), downsampling cap metadata, and the time-series `samples` array. + +The shape of the JSON response depends on which form you use: + +- `--attempt` (or the positional form): top-level run, workflow, and job context, plus a single `attempt` object with the full `samples` array. +- `--job`: top-level run, workflow, and job context, plus a flat `attempts` array of per-attempt summaries. +- `--run`: top-level run context, plus nested `workflows`, `jobs`, and `attempts` arrays. + +For `--job` and `--run`, attempts include the same availability, summary stats, and cap metadata as `--attempt`, but not the `samples` array. + --- ## `depot ci ssh` diff --git a/content/container-builds/how-to-guides/continuous-integration.mdx b/content/container-builds/how-to-guides/continuous-integration.mdx index 96ed463..d857cc2 100644 --- a/content/container-builds/how-to-guides/continuous-integration.mdx +++ b/content/container-builds/how-to-guides/continuous-integration.mdx @@ -20,6 +20,7 @@ Running `depot` in a continuous integration environment is a great way to get fa - [Bitbucket Pipelines](/docs/container-builds/integrations/bitbucket-pipelines) - [Buildkite](/docs/container-builds/integrations/buildkite) - [CircleCI](/docs/container-builds/integrations/circleci) +- [Depot CI](/docs/container-builds/integrations/depot-ci) - [GitHub Actions](/docs/container-builds/integrations/github-actions) - [GitLab CI](/docs/container-builds/integrations/gitlab-ci) - [Google Cloud Build](/docs/container-builds/integrations/google-cloud-build) diff --git a/content/container-builds/integrations/depot-ci.mdx b/content/container-builds/integrations/depot-ci.mdx new file mode 100644 index 0000000..7dad27c --- /dev/null +++ b/content/container-builds/integrations/depot-ci.mdx @@ -0,0 +1,462 @@ +--- +title: Container builds in Depot CI +ogTitle: Use Depot for container builds in Depot CI +description: Get faster container builds with persistent caching and zero emulation in Depot CI workflows. +--- + +You can use Depot for your container image builds inside Depot CI workflows. + +If you haven't migrated your GitHub Actions workflows to Depot CI yet, see the [Depot CI quickstart](/docs/ci/quickstart). Depot CI workflows are compatible with GitHub Actions YAML. For details, see the [Depot CI compatibility reference](/docs/ci/compatibility). + +## Configuration + +You can trigger Depot container builds in Depot CI using a dedicated build action, a bake action, or the Depot CLI directly. + +### Depot build-push action + +The [`depot/build-push-action`](https://github.com/depot/build-push-action) implements the same inputs and outputs as `docker/build-push-action` but uses the Depot CLI to run the build. Use [`depot/setup-action`](https://github.com/depot/setup-action) to install the Depot CLI first. + +```yaml +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + - uses: depot/build-push-action@v1 + with: + project: + context: . +``` + +### Depot bake action + +The [`depot/bake-action`](https://github.com/depot/bake-action) builds all images defined in an HCL, JSON, or Docker Compose file. Use it when you need to build multiple images in a single build request. + +```yaml +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + - uses: depot/bake-action@v1 + with: + project: + files: docker-bake.hcl +``` + +### Depot CLI + +The [`depot/setup-action`](https://github.com/depot/setup-action) installs the `depot` CLI so you can run builds directly from your existing workflows. + +```yaml +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + - run: depot build --project --push --tag repo/image:tag . +``` + +## Authentication + +Depot CI automatically injects `DEPOT_TOKEN` into every job as a short-lived CI job token with full access to your organization's projects and registry. You don't need to configure OIDC trust relationships or store any secrets, the build authenticates without additional setup. + +If you set `DEPOT_TOKEN` as a workflow secret yourself, your value overrides the auto-injected token. This commonly happens after migrating from GitHub Actions, where `DEPOT_TOKEN` was a project token. A project token is scoped to a single project's repositories in the Depot Registry, so pushes to repositories that don't begin with that project ID will fail. To restore the auto-injected behavior, remove the `DEPOT_TOKEN` secret from the dashboard or with `depot ci secrets remove DEPOT_TOKEN`. + +## Pulling private base images + +Dockerfiles that start with `FROM` referencing a private registry need credentials when Depot builds the image. You have two options. + +### Pull through Depot Registry (recommended) + +Configure your private registry as an upstream once from [Registry settings](/orgs/_/registry/settings), then create a Depot repository that mirrors the upstream and reference the Depot Registry URL in your Dockerfile: + +```dockerfile +FROM .registry.depot.dev/: +``` + +Depot fetches the image from your upstream registry, caches layers on its global CDN, and serves subsequent pulls from the cache. The auto-injected `DEPOT_TOKEN` handles pull authentication, so no login step is needed in the workflow. See [Pull-through cache](/docs/registry/pull-through-cache) for setup details and supported providers. + +### Authenticate to the upstream registry + +If pull-through isn't an option, log in to the upstream registry before the build step using `docker/login-action`. The Depot remote builder picks up the credentials and uses them for `FROM` pulls. + +```yaml +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Login to private registry + uses: docker/login-action@v3 + with: + registry: private-registry.example.com + username: ${{ secrets.REGISTRY_USERNAME }} + password: ${{ secrets.REGISTRY_PASSWORD }} + + - uses: depot/build-push-action@v1 + with: + project: + context: . +``` + +## Registry examples + +### Depot Registry + +Use the `save` input to store the built image in the [Depot Registry](/docs/registry/overview) without any additional login steps. You can tag the image with `save-tag` or `save-tags` to retrieve it later with `depot pull` or `docker pull`. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Build and save to Depot Registry + uses: depot/build-push-action@v1 + with: + project: + context: . + save: true + save-tags: | + latest + ${{ github.sha }} +``` + +The saved image can then be pulled from the Depot Registry: + +```shell +# Using the Depot CLI (uses existing CLI credentials) +depot pull --project latest + +# Using Docker (requires docker login first) +docker login registry.depot.dev -u x-token -p $(depot pull-token --project ) +docker pull registry.depot.dev/:latest +``` + +### Amazon ECR + +Use the [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) and [`aws-actions/amazon-ecr-login`](https://github.com/aws-actions/amazon-ecr-login) actions to authenticate to your ECR registry, then build and push with `depot/build-push-action`. AWS authentication uses the OIDC token Depot CI issues when you set `id-token: write`. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: arn:aws:iam:::role/ + aws-region: + + - name: Login to Amazon ECR + id: ecr-login + uses: aws-actions/amazon-ecr-login@v2 + + - name: Build and push + uses: depot/build-push-action@v1 + with: + project: + context: . + push: true + tags: ${{ steps.ecr-login.outputs.registry }}/:latest +``` + +For the OIDC trust relationship setup on the AWS side, see [OIDC with Depot CI](/docs/ci/oidc). + +### GCP Artifact Registry + +Use the [`google-github-actions/auth`](https://github.com/google-github-actions/auth) and [`google-github-actions/setup-gcloud`](https://github.com/google-github-actions/setup-gcloud) actions to authenticate to your Artifact Registry, then build and push with `depot/build-push-action`. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - uses: google-github-actions/auth@v3 + with: + service_account: '...' + workload_identity_provider: '...' + + - uses: google-github-actions/setup-gcloud@v3 + with: + project_id: + + - name: Configure docker for GCP + run: gcloud auth configure-docker -docker.pkg.dev --quiet + + - name: Build and push + uses: depot/build-push-action@v1 + with: + project: + context: . + push: true + tags: -docker.pkg.dev//:latest + provenance: false +``` + +### Azure Container Registry + +Use the [`azure/login`](https://github.com/azure/login) action to authenticate with Azure, then `az acr login` to obtain a registry token before building and pushing with `depot/build-push-action`. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Login to Azure + uses: azure/login@v2 + with: + client-id: ${{ secrets.AZURE_CLIENT_ID }} + tenant-id: ${{ secrets.AZURE_TENANT_ID }} + subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} + + - name: Login to Azure Container Registry + run: az acr login --name + + - name: Build and push + uses: depot/build-push-action@v1 + with: + project: + context: . + push: true + tags: .azurecr.io/: +``` + +### Docker Hub + +Use the [`docker/login-action`](https://github.com/docker/login-action) to authenticate to Docker Hub, then build and push with `depot/build-push-action`. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Login to DockerHub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Build and push + uses: depot/build-push-action@v1 + with: + project: + context: . + push: true + tags: user/app:latest +``` + +### Multiple registries + +Log in to each registry individually and pass multiple tags to push the image to all of them. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: arn:aws:iam:::role/ + aws-region: + + - name: Login to DockerHub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Login to Amazon ECR + id: ecr-login + uses: aws-actions/amazon-ecr-login@v2 + + - name: Build and push + uses: depot/build-push-action@v1 + with: + project: + context: . + push: true + tags: | + /:latest + ${{ steps.ecr-login.outputs.registry }}/:latest +``` + +## Other examples + +### Multi-platform images + +Use the `platforms` input to build for Intel and Arm architectures natively without emulation. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Login to DockerHub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Build and push + uses: depot/build-push-action@v1 + with: + project: + context: . + platforms: linux/amd64,linux/arm64 + push: true + tags: user/app:latest +``` + +### Export an image to Docker + +By default, Depot doesn't return the built image to the client. Pass `load: true` to make the image available in your workflow for subsequent steps like integration tests. + +```yaml +name: Build image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Build and load + uses: depot/build-push-action@v1 + with: + project: + context: . + load: true + tags: test-container + + - name: Run integration test with built container + run: ... +``` + +### Software Bill of Materials + +Use the `sbom` and `sbom-dir` inputs to generate an SBOM for the image and output it to a directory. You can then upload it as a build artifact with `actions/upload-artifact`. + +```yaml +name: Build image with SBOM + +on: + push: + branches: + - main + +jobs: + build: + runs-on: depot-ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: depot/setup-action@v1 + + - name: Build with SBOM + uses: depot/build-push-action@v1 + with: + project: + context: . + sbom: true + sbom-dir: ./sbom-output + + - name: Upload SBOM + uses: actions/upload-artifact@v4 + with: + path: ./sbom-output + name: sbom +``` diff --git a/content/container-builds/integrations/github-actions.mdx b/content/container-builds/integrations/github-actions.mdx index a8611f0..d5e32f7 100644 --- a/content/container-builds/integrations/github-actions.mdx +++ b/content/container-builds/integrations/github-actions.mdx @@ -127,10 +127,11 @@ jobs: The saved image can then be pulled from the Depot Registry: ```shell -# Using the Depot CLI +# Using the Depot CLI (uses existing CLI credentials) depot pull --project latest -# Using Docker +# Using Docker (requires docker login first) +docker login registry.depot.dev -u x-token -p $(depot pull-token --project ) docker pull registry.depot.dev/:latest ``` diff --git a/content/container-builds/quickstart.mdx b/content/container-builds/quickstart.mdx index f5e3b16..b74ab89 100644 --- a/content/container-builds/quickstart.mdx +++ b/content/container-builds/quickstart.mdx @@ -56,6 +56,7 @@ Depot integrates with any CI provider. Use the following guides to help you get - [Bitbucket Pipelines](/docs/container-builds/integrations/bitbucket-pipelines) - [Buildkite](/docs/container-builds/integrations/buildkite) - [CircleCI](/docs/container-builds/integrations/circleci) +- [Depot CI](/docs/container-builds/integrations/depot-ci) - [GitHub Actions](/docs/container-builds/integrations/github-actions) - [GitLab CI](/docs/container-builds/integrations/gitlab-ci) - [Google Cloud Build](/docs/container-builds/integrations/google-cloud-build) diff --git a/content/github-actions/troubleshooting.mdx b/content/github-actions/troubleshooting.mdx index 601cfb8..327a217 100644 --- a/content/github-actions/troubleshooting.mdx +++ b/content/github-actions/troubleshooting.mdx @@ -157,7 +157,7 @@ If you continue to see this error, reach out to support with your workflow run U -## Error: `The operation was canceled.` +## Error: `Step canceled by GitHub` This error indicates that GitHub terminated your job before it completed. Some common reasons for workflow cancellation include manual cancellation, workflow concurrency settings, or memory exhaustion.