{"id":20660649,"url":"https://github.com/depot/build-push-action","last_synced_at":"2025-05-08T00:21:56.480Z","repository":{"id":38362257,"uuid":"496245433","full_name":"depot/build-push-action","owner":"depot","description":"GitHub Action to build and push Docker images with Depot","archived":false,"fork":false,"pushed_at":"2025-02-11T01:50:52.000Z","size":868,"stargazers_count":24,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-01T03:05:08.367Z","etag":null,"topics":["depot","docker","github-actions"],"latest_commit_sha":null,"homepage":"https://github.com/marketplace/actions/build-docker-images-with-depot","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/depot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-25T13:35:14.000Z","updated_at":"2024-09-13T23:01:16.000Z","dependencies_parsed_at":"2023-09-22T07:23:57.672Z","dependency_job_id":"6baa2cb9-bebd-43b3-b667-e9bc17a9d0f3","html_url":"https://github.com/depot/build-push-action","commit_stats":{"total_commits":89,"total_committers":5,"mean_commits":17.8,"dds":0.3370786516853933,"last_synced_commit":"636daae76684e38c301daa0c5eca1c095b24e780"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depot%2Fbuild-push-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depot%2Fbuild-push-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depot%2Fbuild-push-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depot%2Fbuild-push-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/depot","download_url":"https://codeload.github.com/depot/build-push-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252269093,"owners_count":21721246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["depot","docker","github-actions"],"created_at":"2024-11-16T19:05:40.149Z","updated_at":"2025-05-08T00:21:56.424Z","avatar_url":"https://github.com/depot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Build and push a Docker image with Depot - GitHub Action\n\nThis GitHub Action is for building and pushing Docker images with Depot. The action implements the same inputs and outputs as the [`docker/build-push-action`](https://github.com/docker/build-push-action), but uses the [`depot` CLI](https://github.com/depot/cli) to execute the build.\n\n[Depot](https://depot.dev) allows you to build Docker images 5-20x faster on GitHub Actions through optimized build compute and a Docker cache that’s persisted between builds on SSDs.\n\nDepot also supports native [multi-architecture builds](#build-multi-platform-images).\n\n### Table of Contents\n\n- [Build and push a Docker image with Depot - GitHub Action](#build-and-push-a-docker-image-with-depot---github-action)\n  - [Table of Contents](#table-of-contents)\n  - [Setup](#setup)\n  - [Usage](#usage)\n    - [Authentication](#authentication)\n    - [Differences from `docker/build-push-action`](#differences-from-dockerbuild-push-action)\n  - [Inputs](#inputs)\n    - [Depot-specific inputs](#depot-specific-inputs)\n    - [General inputs](#general-inputs)\n  - [Outputs](#outputs)\n  - [Examples](#examples)\n    - [Basic build and push with OIDC token exchange](#basic-build-and-push-with-oidc-token-exchange)\n    - [Basic build and push with Depot API tokens](#basic-build-and-push-with-depot-api-tokens)\n    - [Build multi-platform images](#build-multi-platform-images)\n    - [Other examples](#other-examples)\n  - [License](#license)\n\n## Setup\n\nThe `depot` CLI will need to be available in your workflow, you can use the [`depot/setup-action`](https://github.com/depot/setup-action) to install it:\n\n```yaml\nsteps:\n  - uses: depot/setup-action@v1\n```\n\n## Usage\n\nThis action implements the same inputs and outputs as the [`docker/build-push-action`](https://github.com/docker/build-push-action). You will need to supply your project ID and Depot authentication information, although both can be inferred from the environment. See below for more details.\n\n### Authentication\n\nThis action needs a Depot API token to communicate with your project's builders. You can supply this one of three ways. The third, using OICD, is the preferred method, but you can also supply a token directly.\n\n1. You can supply a user or project API token via the `token` input:\n\n   ```yaml\n   steps:\n     - uses: depot/build-push-action@v1\n       with:\n         token: ${{ secrets.DEPOT_TOKEN }}\n   ```\n\n2. You can supply a user or project API token via the `DEPOT_TOKEN` environment variable:\n\n   ```yaml\n   steps:\n     - uses: depot/build-push-action@v1\n       env:\n         DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}\n   ```\n\n3. Depot supports GitHub's [OpenID Connect](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) tokens via a trust relationship, so your Actions builds can securely authenticate with your Depot projects without any static access tokens. To configure the trust relationship, visit your Depot project settings, then add your repository and desired workflow config to `Trust Relationships`. Then in your workflow, enable the `id-token: write` permission:\n\n   ```yaml\n   permissions:\n     # allow issuing OIDC tokens for this workflow run\n     id-token: write\n     # allow at least reading the repo contents, add other permissions if necessary\n     contents: read\n   steps:\n     # no need to provide a DEPOT_TOKEN\n     - uses: depot/build-push-action@v1\n   ```\n\n### Differences from `docker/build-push-action`\n\n1. Authentication — this action needs to authenticate with a Depot API token to communicate with your project's builders (see above).\n\n2. If you have not configured a `depot.json` file with `depot init`, you can explicitly specify your project ID via the `project` input:\n\n   ```yaml\n   steps:\n     - uses: depot/build-push-action@v1\n       with:\n         project: abc123xyz\n   ```\n\n3. The `builder` input is not supported - this action always runs builds using Depot's hosted builders, if you need to route builds to a local buildx builder, you should use the `docker/build-push-action`.\n4. Depending on how you are using `cache-from` / `cache-to`, you may be able to remove those options. Depot's builders launch with persistent local SSD cache, so unless you wish to push your cache to a registry for other reasons, you can remove them:\n\n   ```diff\n   steps:\n     -\n   -  uses: docker/build-push-action@v1\n   +  uses: depot/build-push-action@v1\n      with:\n   -    cache-from: type=gha\n   -    cache-to: type=gha,mode=max\n   ```\n\n## Inputs\n\n### Depot-specific inputs\n\n| Name              | Type    | Description                                                                                                                                                                                                                                                         |\n| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `project`         | String  | Depot [project](https://depot.dev/docs/core-concepts#projects) ID to route the image build to your projects builders (default: the `depot.json` file at the root of your repo)                                                                                      |\n| `token`           | String  | You must authenticate with the Depot API to communicate with your projects builders ([see Authentication above](#authentication))                                                                                                                                   |\n| `build-platform`  | String  | The platform to use for the build ( `linux/amd64` or `linux/arm64`)                                                                                                                                                                                                 |\n| `buildx-fallback` | Boolean | If true, this action will fallback to using `docker buildx build` if `depot build` is unable to acquire a builder connection. This requires installing buildx with [`docker/setup-buildx-action`](https://github.com/docker/setup-buildx-action) (default: `false`) |\n| `lint`            | Boolean | Lint dockerfiles and fail build if any issues are of `error` severity. (default `false`)                                                                                                                                                                            |\n| `lint-fail-on`    | String  | Severity of linter issue to cause the build to fail. (`error`, `warn`, `info`, `none`)                                                                                                                                                                              |\n| `save`            | Boolean | Save the image to the Depot ephemeral registry (for use with the [depot/pull-action](https://github.com/depot/pull-action))                                                                                                                                         |\n\n### General inputs\n\nThe following inputs can be used as `step.with` keys and match the inputs from [`docker/build-push-action`](https://github.com/docker/build-push-action):\n\n| Name               | Type        | Description                                                                                                                                                                                                                  |\n| ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `add-hosts`        | List/CSV    | List of [customs host-to-IP mapping](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) (e.g., `docker:10.180.0.1`)                                                 |\n| `allow`            | List/CSV    | List of [extra privileged entitlement](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#allow) (e.g., `network.host,security.insecure`)                                                           |\n| `attests`          | List        | List of [attestation](https://docs.docker.com/build/attestations/) parameters (e.g., `type=sbom,generator=image`)                                                                                                            |\n| `build-args`       | List        | List of [build-time variables](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#build-arg)                                                                                                        |\n| `build-contexts`   | List        | List of additional [build contexts](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#build-context) (e.g., `name=path`)                                                                           |\n| `cache-from`       | List        | List of [external cache sources](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-from) (e.g., `type=local,src=path/to/dir`)                                                                |\n| `cache-to`         | List        | List of [cache export destinations](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-to) (e.g., `type=local,dest=path/to/dir`)                                                              |\n| `cgroup-parent`    | String      | Optional [parent cgroup](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) for the container used in the build                                                         |\n| `context`          | String      | Build's context is the set of files located in the specified [`PATH` or `URL`](https://docs.docker.com/engine/reference/commandline/build/) (default [Git context](https://github.com/docker/build-push-action#git-context)) |\n| `file`             | String      | Path to the Dockerfile. (default `{context}/Dockerfile`)                                                                                                                                                                     |\n| `labels`           | List        | List of metadata for an image                                                                                                                                                                                                |\n| `load`             | Bool        | [Load](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#load) is a shorthand for `--output=type=docker` (default `false`)                                                                         |\n| `network`          | String      | Set the networking mode for the `RUN` instructions during build                                                                                                                                                              |\n| `no-cache`         | Bool        | Do not use cache when building the image (default `false`)                                                                                                                                                                   |\n| `no-cache-filters` | List/CSV    | Do not cache specified stages                                                                                                                                                                                                |\n| `outputs`          | List        | List of [output destinations](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#output) (format: `type=local,dest=path`)                                                                           |\n| `platforms`        | List/CSV    | List of [target platforms](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#platform) for build                                                                                                   |\n| `provenance`       | Bool/String | Generate [provenance](https://docs.docker.com/build/attestations/slsa-provenance/) attestation for the build (shorthand for `--attest=type=provenance`)                                                                      |\n| `pull`             | Bool        | Always attempt to pull all referenced images (default `false`)                                                                                                                                                               |\n| `push`             | Bool        | [Push](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#push) is a shorthand for `--output=type=registry` (default `false`)                                                                       |\n| `sbom`             | Bool/String | Generate [SBOM](https://docs.docker.com/build/attestations/sbom/) attestation for the build (shorthand for `--attest=type=sbom`)                                                                                             |\n| `sbom-dir`         | String      | Save all image [SBOM](https://docs.docker.com/build/attestations/sbom/) to this output directory                                                                                                                             |\n| `secrets`          | List        | List of [secrets](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#secret) to expose to the build (e.g., `key=string`, `GIT_AUTH_TOKEN=mytoken`)                                                  |\n| `secret-files`     | List        | List of [secret files](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#secret) to expose to the build (e.g., `key=filename`, `MY_SECRET=./secret.txt`)                                           |\n| `shm-size`         | String      | Size of [`/dev/shm`](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-size-of-devshm---shm-size) (e.g., `2g`)                                                                                    |\n| `ssh`              | List        | List of [SSH agent socket or keys](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#ssh) to expose to the build                                                                                   |\n| `tags`             | List/CSV    | List of tags                                                                                                                                                                                                                 |\n| `target`           | String      | Sets the target stage to build                                                                                                                                                                                               |\n| `ulimit`           | List        | [Ulimit](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-set-ulimits---ulimit) options (e.g., `nofile=1024:1024`)                                                                               |\n| `github-token`     | String      | GitHub Token used to authenticate against a repository for [Git context](https://github.com/docker/build-push-action#git-context) (default `${{ github.token }}`)                                                            |\n\n## Outputs\n\n| Name         | Type   | Description           |\n| ------------ | ------ | --------------------- |\n| `imageid`    | String | Image ID              |\n| `digest`     | String | Image digest          |\n| `metadata`   | JSON   | Build result metadata |\n| `project-id` | String | Depot Project ID      |\n| `build-id`   | String | Depot Build ID        |\n\n## Examples\n\nBelow are examples of how to use `depot/build-push-action` to build your Docker images using Depot builders. For all examples, it is assumed that you are either specifying the Depot project ID via the `project` or input, environment variable, or using a `depot.json` file.\n\n### Basic build and push with OIDC token exchange\n\nSee our [trust relationship documentation](https://depot.dev/docs/cli/authentication#oidc-trust-relationships) for details on configuring this exchange.\n\n```yaml\nname: Build image\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  docker-image:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      id-token: write\n    steps:\n      - name: Checkout repo\n        uses: actions/checkout@v3\n\n      - name: Set up Depot CLI\n        uses: depot/setup-action@v1\n\n      - name: Login to DockerHub\n        uses: docker/login-action@v2\n        with:\n          username: ${{ secrets.DOCKERHUB_USERNAME }}\n          password: ${{ secrets.DOCKERHUB_TOKEN }}\n\n      - name: Build and push\n        uses: depot/build-push-action@v1\n        with:\n          # if no depot.json file is at the root of your repo, you must specify the project id\n          project: \u003cyour-depot-project-id\u003e\n          push: true\n          tags: user/app:latest\n```\n\n### Basic build and push with Depot API tokens\n\nYou can use either Depot [project tokens](https://depot.dev/docs/cli/authentication#project-tokens) or [user tokens](https://depot.dev/docs/cli/authentication#user-access-tokens) in the `token` input.\n\n**Note:** Project tokens are the recommendation if OIDC tokens are not an option.\n\n```yaml\nname: Build image\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  docker-image:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout repo\n        uses: actions/checkout@v3\n\n      - name: Set up Depot CLI\n        uses: depot/setup-action@v1\n\n      - name: Login to DockerHub\n        uses: docker/login-action@v2\n        with:\n          username: ${{ secrets.DOCKERHUB_USERNAME }}\n          password: ${{ secrets.DOCKERHUB_TOKEN }}\n\n      - name: Build and push\n        uses: depot/build-push-action@v1\n        with:\n          # if no depot.json file is at the root of your repo, you must specify the project id\n          project: \u003cyour-depot-project-id\u003e\n          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}\n          push: true\n          tags: user/app:latest\n          build-args: |\n            FOO=bar\n```\n\n### Build multi-platform images\n\nDepot supports building truly native [multi-platform images](https://depot.dev/blog/multi-platform-docker-images-in-github-actions), no emulation needed.\n\n```yaml\nname: Build image\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  docker-image:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout repo\n        uses: actions/checkout@v3\n\n      - name: Set up Depot CLI\n        uses: depot/setup-action@v1\n\n      - name: Login to DockerHub\n        uses: docker/login-action@v2\n        with:\n          username: ${{ secrets.DOCKERHUB_USERNAME }}\n          password: ${{ secrets.DOCKERHUB_TOKEN }}\n\n      - name: Build and push\n        uses: depot/build-push-action@v1\n        with:\n          # if no depot.json file is at the root of your repo, you must specify the project id\n          project: \u003cyour-depot-project-id\u003e\n          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}\n          platforms: linux/amd64,linux/arm64\n          push: true\n          tags: user/app:latest\n```\n\n### Other examples\n\n- [Build and push image to Amazon ECR](/docs/build-and-push-ecr.md)\n- [Build and push image to GCP Artifact Registry](/docs/build-and-push-artifact-registry.md)\n- [Build and push to multiple registries](/docs/build-and-push-multiple.md)\n- [Export image to Docker](/docs/export-to-docker.md)\n- [Lint and Build image](/docs/lint-and-build.md)\n- [Build image with Software Bill of Materials (SBOM)](/docs/build-with-sbom.md)\n\n## License\n\nMIT License, see `LICENSE`.\n\nCode derived from `docker/build-push-action` copyright 2013-2018 Docker, Inc., Apache License, Version 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepot%2Fbuild-push-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdepot%2Fbuild-push-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepot%2Fbuild-push-action/lists"}