push¶
Performs a Docker push of the image created by build.
By following the conventions no additional flags are needed, but the following flags are available:
| Flag | Description |
|---|---|
--file,-f <path to Dockerfile> | Used to override the default Dockerfile location (which is $PWD) |
$ push --file docker/Dockerfile.build
Each tag is pushed in its own request: the build stages, the commit, the branch, and latest on the default branch. Export stages (named export*) are never pushed — build writes their output to a local directory and tags no image for them, so a push of their stage tag would fail.
Throttling¶
A registry that rate-limits pushes answers with HTTP 429 (on ECR, toomanyrequests: Rate exceeded). A push that was throttled is retried up to three times, waiting 2, 4 and 8 seconds between attempts, before push fails. Other push errors are not retried.
GitHub Actions outputs¶
When running in GitHub Actions, the push command writes the following step outputs to $GITHUB_OUTPUT:
| Output | Description |
|---|---|
image-name | Full image name without tag |
digest | Image digest (sha256:...) |
This enables integration with artifact attestations for supply chain security.
Note
When BUILDKIT_HOST is set, images are pushed during build and push becomes a no-op. In that case, the outputs come from the build step instead.
See GitHub Actions for a full workflow example.