Docker with GitHub Actions
Build and publish Docker images in GitHub Actions with reproducible metadata, cache controls, least-privilege registry authentication and attestations.
Integration boundary
GitHub-hosted or self-hosted runners can drive Docker Buildx and publish immutable image digests to a registry after repository events pass policy.
Supported approaches
Docker official actions
Compose setup-buildx, login, metadata and build-push actions for common registry workflows.
Direct Docker CLI
Run explicit docker buildx commands where action abstraction is not desired.
Prerequisites
- A Dockerfile with an intentional build context
- Registry authentication scoped to the target repository
- A tag and digest strategy
- Pinned build dependencies and actions
Implementation
Create a Buildx builder
Use a supported builder and make platform targets explicit.
Generate immutable metadata
Publish useful tags while retaining the image digest as the deployment identity.
Use bounded cache
Select cache sources and scopes that do not allow untrusted builds to poison privileged outputs.
Verification
Inspect the published digest
Confirm the registry manifest contains the expected platforms and annotations.
Pull by digest
Prove the exact published artifact is retrievable from the deployment environment.
Verify provenance
Validate any generated build attestation against the repository and workflow identity.
Common failure modes
- Mutable latest tag used as deployment identity
- Secrets available to untrusted pull-request code
- Build context includes credentials or unnecessary files
- Cross-platform image published without testing each architecture
Related engineering templates
Follow Docker and GitHub Actions failures and fixes
A useful digest about twice a week with new error references, tools, integration notes and production lessons. No daily noise.