{"id":15662322,"url":"https://github.com/int128/docker-build-cache-config-action","last_synced_at":"2026-02-14T23:10:56.935Z","repository":{"id":37048760,"uuid":"412654149","full_name":"int128/docker-build-cache-config-action","owner":"int128","description":"Generate effective cache parameters for docker/build-push-action in GitHub Actions","archived":false,"fork":false,"pushed_at":"2025-04-05T07:08:13.000Z","size":5134,"stargazers_count":21,"open_issues_count":5,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T23:48:03.128Z","etag":null,"topics":["buildkit","docker","github-actions"],"latest_commit_sha":null,"homepage":"https://medium.com/@int128/effective-buildkit-cache-in-github-actions-e36d08804ffb","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/int128.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":"2021-10-02T00:45:12.000Z","updated_at":"2025-04-05T07:08:14.000Z","dependencies_parsed_at":"2023-10-03T02:26:08.754Z","dependency_job_id":"7654a5ef-e5d3-4000-8664-87af332e5051","html_url":"https://github.com/int128/docker-build-cache-config-action","commit_stats":{"total_commits":928,"total_committers":3,"mean_commits":309.3333333333333,"dds":"0.042025862068965525","last_synced_commit":"c315f66c8bf92a33a39eacbb93939dbfdc01bd94"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":"int128/typescript-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/int128%2Fdocker-build-cache-config-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/int128%2Fdocker-build-cache-config-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/int128%2Fdocker-build-cache-config-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/int128%2Fdocker-build-cache-config-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/int128","download_url":"https://codeload.github.com/int128/docker-build-cache-config-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248800087,"owners_count":21163404,"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":["buildkit","docker","github-actions"],"created_at":"2024-10-03T13:31:43.509Z","updated_at":"2026-02-06T23:05:27.059Z","avatar_url":"https://github.com/int128.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docker-build-cache-config-action [![ts](https://github.com/int128/docker-build-cache-config-action/actions/workflows/ts.yaml/badge.svg)](https://github.com/int128/docker-build-cache-config-action/actions/workflows/ts.yaml)\n\nThis action generates `cache-from` and `cache-to` inputs of [docker/build-push-action](https://github.com/docker/build-push-action) for the effective cache strategy in the pull request based development flow.\n\n## Problem to solve\n\n[docker/build-push-action](https://github.com/docker/build-push-action) supports the cache management using Buildx (BuildKit).\nIt can import and export a cache by the following parameters:\n\n```yaml\ncache-from: type=registry,ref=REGISTRY/REPOSITORY:TAG\ncache-to: type=registry,ref=REGISTRY/REPOSITORY:TAG,mode=max\n```\n\nIf a same tag is used in the pull request based development flow, it will cause a cache miss.\nFor example,\n\n1. Initially, the cache points to main branch\n1. When a pull request B is opened,\n   - It imports the cache of main branch\n   - The cache hits\n   - It exports the cache of pull request B\n1. When a pull request C is opened,\n   - It imports the cache of pull request B\n   - The cache misses\n   - It exports the cache of pull request C\n1. When the pull request B is merged into main,\n   - It imports the cache of pull request C\n   - The cache misses\n   - It exports the cache of main branch\n\nTherefore, it needs to prevent the cache pollution caused by a pull request.\n\n## How to solve\n\nKeep a cache tag tracking the corresponding branch.\n\nWhen the main branch is pushed, it imports a cache from the main tag.\nIt finally exports a cache to the main tag for the future build.\n\n```yaml\ncache-from: type=registry,ref=REGISTRY/REPOSITORY:main\ncache-to: type=registry,ref=REGISTRY/REPOSITORY:main,mode=max\n```\n\nWhen a pull request is created or updated, it only imports a cache from the main tag.\nIt does not export a cache to the main tag to prevent the cache pollution.\n\n```yaml\ncache-from: type=registry,ref=REGISTRY/REPOSITORY:main\ncache-to:\n```\n\nIf the base branch of the pull request is not main, it imports both base tag and main tag.\n\n```yaml\ncache-from: |\n  type=registry,ref=REGISTRY/REPOSITORY:base\n  type=registry,ref=REGISTRY/REPOSITORY:main\ncache-to:\n```\n\nHere is the diagram of this cache strategy.\n\n![effective-build-cache-diagram](effective-build-cache-diagram.drawio.svg)\n\nThis action generates the cache parameters by this strategy.\n\n```yaml\n- uses: int128/docker-build-cache-config-action@v1\n  id: cache\n  with:\n    image: ghcr.io/${{ github.repository }}/cache\n- uses: docker/build-push-action@v2\n  with:\n    cache-from: ${{ steps.cache.outputs.cache-from }}\n    cache-to: ${{ steps.cache.outputs.cache-to }}\n```\n\n## Examples\n\n### Build with docker/build-push-action\n\nHere is an example to build a container image with [docker/build-push-action](https://github.com/docker/build-push-action).\n\n```yaml\n- uses: docker/metadata-action@v3\n  id: metadata\n  with:\n    images: ghcr.io/${{ github.repository }}\n- uses: int128/docker-build-cache-config-action@v1\n  id: cache\n  with:\n    image: ghcr.io/${{ github.repository }}/cache\n- uses: docker/build-push-action@v2\n  id: build\n  with:\n    push: true\n    tags: ${{ steps.metadata.outputs.tags }}\n    labels: ${{ steps.metadata.outputs.labels }}\n    cache-from: ${{ steps.cache.outputs.cache-from }}\n    cache-to: ${{ steps.cache.outputs.cache-to }}\n```\n\nIt will create the following image tags:\n\n```\nghcr.io/${{ github.repository }}:main\nghcr.io/${{ github.repository }}:pr-1\nghcr.io/${{ github.repository }}/cache:main\n```\n\nSee [README_EXAMPLES.md](README_EXAMPLES.md) for more examples.\n\n### Build with docker/bake-action\n\nHere is an example to build a container image with [docker/bake-action](https://github.com/docker/bake-action).\n\n```yaml\n- uses: docker/metadata-action@v3\n  id: metadata\n  with:\n    images: ghcr.io/${{ github.repository }}\n- uses: int128/docker-build-cache-config-action@v1\n  id: cache\n  with:\n    image: ghcr.io/${{ github.repository }}/cache\n- uses: docker/bake-action@v5\n  id: build\n  with:\n    push: true\n    files: |\n      ./docker-bake.hcl\n      ${{ steps.metadata.outputs.bake-file }}\n      ${{ steps.cache.outputs.bake-file }}\n```\n\n```hcl\n# docker-bake.hcl\ntarget \"docker-metadata-action\" {}\n\ntarget \"docker-build-cache-config-action\" {}\n\ntarget \"default\" {\n  inherits = [\"docker-metadata-action\", \"docker-build-cache-config-action\"]\n  context = \".\"\n}\n```\n\n## Specification\n\n### Inputs\n\n| Name                 | Default                            | Description                                                                                    |\n| -------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `image`              | (required)                         | Image repository to import/export cache                                                        |\n| `cache-type`         | `registry`                         | Type of cache backend (for source and destination). Can be registry, local, inline, gha and s3 |\n| `flavor`             | -                                  | Flavor (multiline string)                                                                      |\n| `extra-cache-from`   | -                                  | Extra flag to `cache-from`                                                                     |\n| `extra-cache-to`     | -                                  | Extra flag to `cache-to`                                                                       |\n| `pull-request-cache` | -                                  | Import and export a pull request cache                                                         |\n| `cache-key`          | -                                  | Custom cache key                                                                               |\n| `cache-key-fallback` | -                                  | Custom cache key to fallback                                                                   |\n| `bake-target`        | `docker-build-cache-config-action` | Bake target name                                                                               |\n\n`flavor` is mostly compatible with [docker/metadata-action](https://github.com/docker/metadata-action#flavor-input)\nexcept this action supports only `prefix` and `suffix`.\n\n`extra-cache-to` is added to `cache-to` parameter only when it needs to export cache.\n\nNote that `cache-key` and `cache-key-fallback` are experimental.\nThe specification may change in the future.\n\n### Outputs\n\n| Name         | Description                            |\n| ------------ | -------------------------------------- |\n| `cache-from` | Parameter for docker/build-push-action |\n| `cache-to`   | Parameter for docker/build-push-action |\n| `bake-file`  | Bake definition file                   |\n\n### Events\n\nThis action exports a cache on the following events:\n\n- `push` event to a branch\n  - Export a cache to the tag corresponding to the pushed branch\n- `pull_request` event\n  - Export a cache to the tag corresponding to the pull request number (only if `pull-request-cache` is set)\n- `issue_comment` event to a pull request\n  - Export a cache to the tag corresponding to the pull request number (only if `pull-request-cache` is set)\n- Other events\n  - Export nothing\n\nIt imports a cache on the following events:\n\n- `push` event to a branch\n  - Import a cache from the tag corresponding to the pushed branch\n- `pull_request` event\n  - Import a cache from the tag corresponding to the pull request number\n  - Import a cache from the tag corresponding to the base branch\n  - Import a cache from the tag corresponding to the default branch\n- `issue_comment` event to a pull request\n  - Import a cache from the tag corresponding to the pull request number\n  - Import a cache from the tag corresponding to the base branch\n  - Import a cache from the tag corresponding to the default branch\n- Other events\n  - Import a cache from the tag corresponding to the default branch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fint128%2Fdocker-build-cache-config-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fint128%2Fdocker-build-cache-config-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fint128%2Fdocker-build-cache-config-action/lists"}