A thin wrapper around the official docker/build-push-action that simplifies common use cases while maintaining full compatibility.
- Automatic tag generation: Smart defaults for latest, SHA tags, and multi-registry support
- Simplified inputs: Clean interface without complex configuration
- Leverages docker/metadata-action: For consistent label and tag generation
- Input validation: Prevents invalid configurations and common mistakes
- Multi-arch support: Automatically sets up QEMU when needed
- Better summaries: Clear GitHub Actions summaries with all build details
- Security features: Support for SBOM and provenance attestations
Important: You must authenticate with your container registry before using this action. This action does not handle authentication.
# For GitHub Container Registry - uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} # For AWS ECR (using OIDC) - uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ vars.AWS_BUILD_ROLE }} aws-region: us-east-1 # For Docker Hub - uses: docker/login-action@v3 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }}The simplest way to use this action - just provide the image repository and primary tag. The action automatically adds useful tags like :latest (on default branch) and :sha-<commit> for traceability.
# Single registry - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: v1.2.3 # Automatically generates: # - myregistry.io/myapp:v1.2.3 # - myregistry.io/myapp:sha-abc1234 (first 7 chars of commit SHA) # - myregistry.io/myapp:latest (if on default branch, usually 'main') # Multiple registries (newline-delimited) # Note: You must authenticate to each registry before this action - uses: skyhook-io/docker-build-push-action@v1 with: image: | ghcr.io/${{ github.repository }} 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp myregistry.azurecr.io/myapp base_tag: v1.2.3 # Generates the same 3 tags for each registry- uses: skyhook-io/docker-build-push-action@v1 with: # Tags are newline-delimited (one per line) tags: | myregistry.io/myapp:latest myregistry.io/myapp:v1.2.3 ghcr.io/${{ github.repository }}:v1.2.3 context: . dockerfile: Dockerfile| Input | Description | Required | Default |
|---|---|---|---|
image | Base image repository (e.g., ghcr.io/org/app). Supports multiple repositories (newline-delimited) | Yes* | - |
base_tag | Primary tag (e.g., v1.2.3) | Yes* | - |
tag_latest_on_default_branch | Add :latest tag when building from default branch (main/master) | No | true |
tag_sha | Add :sha-<short> tag for traceability | No | true |
include_ref_tags | Generate branch/PR tags (e.g., pr-123, feature-branch) | No | false |
include_semver_tags | Generate major/minor tags from semver (e.g., 1, 1.2 from v1.2.3) | No | true |
| Input | Description | Required | Default |
|---|---|---|---|
tags | Explicit list of image:tag combinations (newline-delimited) | Yes* | - |
*Must provide either (image + base_tag) OR tags
| Input | Description | Required | Default |
|---|---|---|---|
context | Build context path | No | . |
dockerfile | Path to Dockerfile | No | Dockerfile |
platforms | Comma-separated platforms | No | linux/amd64 |
build_args | Multiline KEY=VALUE build args | No | - |
target | Target build stage | No | - |
secrets | Build secrets (multiline) | No | - |
ssh | SSH agent sockets/keys | No | - |
| Input | Description | Required | Default |
|---|---|---|---|
cache_from | Cache sources | No | type=gha |
cache_to | Cache destinations | No | type=gha,mode=max |
no_cache | Disable cache | No | false |
| Input | Description | Required | Default |
|---|---|---|---|
push | Push to registry | No | true |
load | Load into Docker daemon (mutually exclusive with push) | No | false |
pull | Always pull newer base images | No | false |
| Input | Description | Required | Default |
|---|---|---|---|
provenance | Enable provenance attestation | No | false |
sbom | Generate SBOM attestation | No | false |
All parameters prefixed with buildx_ are passed directly to docker/setup-buildx-action:
| Input | Description | Required | Default |
|---|---|---|---|
buildx_version | Buildx version (e.g., v0.3.0, latest) | No | - |
buildx_name | Builder name (auto-generated if not specified) | No | - |
buildx_driver | Builder driver (docker-container, docker, kubernetes, remote) | No | - |
buildx_driver_opts | Driver-specific options (e.g., image=moby/buildkit:master) | No | - |
buildx_buildkitd_flags | BuildKit daemon flags | No | - |
buildx_buildkitd_config | BuildKit daemon config file | No | - |
buildx_buildkitd_config_inline | BuildKit daemon config inline | No | - |
buildx_install | Set up docker build as alias to docker buildx | No | - |
buildx_use | Switch to this builder instance | No | - |
buildx_endpoint | Address for docker socket or context | No | - |
buildx_platforms | Fixed platforms for current node | No | - |
buildx_append | Append additional nodes to builder (YAML) | No | - |
buildx_keep_state | Keep BuildKit state on cleanup | No | - |
buildx_cache_binary | Cache buildx binary | No | - |
buildx_cleanup | Cleanup temp files and remove builder | No | - |
| Output | Description |
|---|---|
imageid | Image ID |
digest | Image content-addressable digest |
metadata | Build result metadata |
tags_list | Newline-delimited list of image:tag combinations |
# Simple case - generates v1.2.3, sha-abc1234, and latest (if on default branch) - uses: skyhook-io/docker-build-push-action@v1 with: image: ghcr.io/${{ github.repository }} base_tag: v${{ github.event.release.tag_name }} # Include branch/PR tags for development builds - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: ${{ github.ref_name }}-${{ github.run_number }} include_ref_tags: true # Adds branch name or pr-123 tags # Clean release tags only - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: v1.2.3 tag_sha: false # No SHA tag tag_latest_on_default_branch: true # Still add latest on default branch include_semver_tags: true # Also generates '1' and '1.2' tags# Authenticate to each registry first - uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - uses: skyhook-io/cloud-login@v1 with: provider: aws region: us-east-1 aws_role_to_assume: ${{ vars.AWS_BUILD_ROLE }} login_to_container_registry: true # Then push to all registries with the same tags - uses: skyhook-io/docker-build-push-action@v1 with: image: | ghcr.io/${{ github.repository }} 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp base_tag: v1.2.3- uses: skyhook-io/docker-build-push-action@v1 with: tags: myregistry.io/myapp:latest platforms: linux/amd64,linux/arm64,linux/arm/v7 push: true- uses: skyhook-io/docker-build-push-action@v1 with: tags: myregistry.io/myapp:${{ github.sha }} build_args: | VERSION=${{ github.ref_name }} BUILD_DATE=${{ github.event.head_commit.timestamp }} VCS_REF=${{ github.sha }}- uses: skyhook-io/docker-build-push-action@v1 with: tags: myregistry.io/myapp:test target: test load: true # Load for local testing push: falsestrategy: matrix: include: - registry: ghcr.io image: ${{ github.repository }} - registry: docker.io image: myorg/myapp steps: - uses: skyhook-io/docker-build-push-action@v1 with: tags: ${{ matrix.registry }}/${{ matrix.image }}:${{ github.ref_name }}- id: build uses: skyhook-io/docker-build-push-action@v1 with: tags: myregistry.io/myapp:v1.2.3 - name: Deploy image run: | echo "Deploying images:" echo "${{ steps.build.outputs.tags_list }}" # Use the digest for immutable reference kubectl set image deployment/myapp app=myregistry.io/myapp@${{ steps.build.outputs.digest }}# Generate SBOM and provenance for supply chain security - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: v1.2.3 provenance: true # Generate provenance attestation sbom: true # Generate SBOM attestation# Configure buildx with custom driver and settings - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: v1.2.3 buildx_driver: docker-container buildx_driver_opts: | network=host image=moby/buildkit:v0.12.0 buildx_install: true buildx_platforms: linux/amd64,linux/arm64 # Use remote BuildKit instance - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: v1.2.3 buildx_driver: remote buildx_endpoint: tcp://buildkit.example.com:8125 # Configure buildx with specific builder instance - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: v1.2.3 buildx_name: my-custom-builder buildx_driver: kubernetes buildx_driver_opts: | namespace=buildkit replicas=2 buildx_use: true # Use specific buildx version with custom flags - uses: skyhook-io/docker-build-push-action@v1 with: image: myregistry.io/myapp base_tag: v1.2.3 buildx_version: v0.11.2 buildx_buildkitd_flags: --debug --allow-insecure-entitlement network.host buildx_install: trueThis action is fully compatible with docker/build-push-action. To migrate:
- Change the action reference
- No other changes needed - all inputs are compatible
- Optionally simplify complex tag configurations using our
tagsinput
- uses: docker/build-push-action@v5 with: tags: | user/repo:latest user/repo:${{ github.sha }}- uses: skyhook-io/docker-build-push-action@v1 with: tags: | user/repo:latest user/repo:${{ github.sha }}This action uses docker/metadata-action to automatically generate rich OCI labels including:
org.opencontainers.image.created- Build timestamporg.opencontainers.image.revision- Git SHAorg.opencontainers.image.source- Repository URLorg.opencontainers.image.url- Build run URLorg.opencontainers.image.version- Git ref nameorg.opencontainers.image.title- Repository nameorg.opencontainers.image.description- Repository descriptionorg.opencontainers.image.licenses- Repository license (if detected)org.opencontainers.image.authors- Repository authors
- Automatically sets up Docker Buildx and QEMU (for multi-arch builds)
- Registry authentication must be configured separately for each registry
- Cannot use
push: trueandload: truetogether (validated automatically) - When using multi-registry support, the same image layers are pushed to all registries
- Uses docker/metadata-action for consistent label and tag generation
- Order of tags is preserved (using stable de-duplication)