Skip to content

feat: docker multi-arch composite actions #1347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 28 commits into from
Oct 10, 2025
Merged

feat: docker multi-arch composite actions #1347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
1327ced
Initial commit with docker-build-push-image, docker-export-digest, an…
ricky-undeadcoders Sep 15, 2025
d30836f
Initial commit with READMEs
ricky-undeadcoders Sep 15, 2025
d884f81
Add input/output descriptions for docker-build-push-image, tidy them …
ricky-undeadcoders Sep 18, 2025
4526d81
docs updates and adding in QEMU to docker-build-push-action
ricky-undeadcoders Sep 19, 2025
b37f49d
Docs updates and including dockerhub registry input
ricky-undeadcoders Sep 19, 2025
810ea7b
Action doesn't like the template syntax in an input description?
ricky-undeadcoders Sep 19, 2025
d1f1ef8
docker-import-digests-push-manifest: add registries input and dry-run…
ricky-undeadcoders Sep 19, 2025
5e053bc
docker-import-digests-push-manifest: add registries input and dry-run…
ricky-undeadcoders Sep 19, 2025
2bee1ac
docker-import-digests-push-manifest: Add some error handling
ricky-undeadcoders Sep 19, 2025
9cc653d
docker-import-digests-push-manifest: Add some error handling
ricky-undeadcoders Sep 19, 2025
f8f110f
docker-import-digests-push-manifest: Add some error handling
ricky-undeadcoders Sep 19, 2025
0476051
docker-import-digests-push-manifest: Add some error handling
ricky-undeadcoders Sep 19, 2025
691ec30
docker-import-digests-push-manifest: Add some error handling
ricky-undeadcoders Sep 19, 2025
df2148c
Updated error message
ricky-undeadcoders Sep 19, 2025
6e2c378
Add warnings when no images are pushed.
ricky-undeadcoders Sep 20, 2025
84dbe66
Add better handling for default buildkitd config
ricky-undeadcoders Sep 20, 2025
abf9d2a
Add warning when default buildkitd config doesn't exist
ricky-undeadcoders Sep 20, 2025
fc3c93f
Various docs updates
ricky-undeadcoders Sep 23, 2025
8162046
prettier
ricky-undeadcoders Sep 23, 2025
d875e6f
Updated inputs in README
ricky-undeadcoders Sep 23, 2025
5089c2d
remove test notes
ricky-undeadcoders Sep 24, 2025
c0c6bba
Add some help text to docker-build-push-image
ricky-undeadcoders Oct 1, 2025
01752f7
Switch to cloned shared workflows for docker-import-digests-push-mani…
ricky-undeadcoders Oct 2, 2025
6009ebe
Fix login to gar action in docker-import-digests-push-manifest
ricky-undeadcoders Oct 2, 2025
8395371
adding recommendations
ricky-undeadcoders Oct 2, 2025
7edbaf4
Add login logic to docker-import-digests-push-manifest
ricky-undeadcoders Oct 8, 2025
53b7906
Fix missing metadata in docker-import-digests-push-manifest
ricky-undeadcoders Oct 8, 2025
acd325c
update README for docker-import-digests-push-manifest
ricky-undeadcoders Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 138 additions & 0 deletions actions/docker-build-push-image/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# docker-build-push-image

This is a composite GitHub Action, used to build and push docker images to private Grafana registries.
It builds registry URLs for Grafana's registries, authenticates to them, and then
uses [docker/build-push-action] to build and push the image(s).

This action can work 1 of 2 ways:

1. It can be run on a single runner, and if multiple `platforms` are configured then buildx/QEMU emulation is used.
2. It can be used in conjunction with [docker-export-digest] and [docker-import-digests-push-manifest] to push untagged
images whose digests are later exported and merged into a tagged docker manifest. For true multi-arch builds.

This can push to the following registries:

1. Google Artifact Registry
2. DockerHub

[docker/build-push-action]: https://github.com/docker/build-push-action
[docker-build-push-image]: ../docker-build-push-image/README.md
[docker-export-digest]: ../docker-export-digest/README.md
[docker-import-digests-push-manifest]: ../docker-import-digests-push-manifest/README.md

<!-- x-release-please-start-version -->

```yaml
name: Build a Docker Image

on:
push:
branches:
- main

jobs:
build-push-image:
permissions:
contents: read
id-token: write
steps:
- uses: grafana/shared-workflows/actions/docker-build-push-image@docker-build-push-image/v0.0.0
with:
platforms: linux/arm64,linux/amd64
tags: |
${{ github.sha }}
main
push: true
registries: "gar,dockerhub"
```

<!-- x-release-please-end-version -->

## Inputs

| Name | Type | Description |
| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build-args` | String | List of arguments necessary for the Docker image to be built. Passed to `docker/build-push-action`. |
| `build-contexts` | String | List of additional build contexts (e.g., name=path). Passed to `docker/build-push-action`. |
| `buildkitd-config` | String | The buildkitd config file to use. Defaults to `/etc/buildkitd.toml` if you're using Grafana's self-hosted runners. Passed to `docker/setup-buildx-action`. |
| `buildkitd-config-inline` | String | The buildkitd inline config to use. Passed to `docker/setup-buildx-action`. |
| `cache-from` | String | Where cache should be fetched from. Passed to `docker/build-push-action`. |
| `cache-to` | String | Where cache should be stored to. Passed to `docker/build-push-action`. |
| `context` | String | Path to the Docker build context. Passed to `docker/build-push-action`. |
| `docker-buildx-driver` | String | The driver to use for Docker Buildx. Passed to `docker/setup-buildx-action`. |
| `dockerhub-registry` | String | DockerHub Registry to store docker images in. |
| `dockerhub-repository` | String | DockerHub Repository to store docker images in. Default: github.repository |
| `file` | String | The dockerfile to use. Passed to `docker/build-push-action`. |
| `gar-delete-credentials-file` | Boolean | Delete the Google credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. |
| `gar-environment` | String | Environment for pushing artifacts (can be either dev or prod). This sets the GAR Project (gar-project) to either `grafanalabs-dev` or `grafanalabs-global`. |
| `gar-image` | String | Name of the image to build. Default: `${GitHub Repo Name}`. |
| `gar-registry` | String | Google Artifact Registry to store docker images in. |
| `gar-repository` | String | Override the 'repo_name' used to construct the GAR repository name. Only necessary when the GAR includes a repo name that doesn't match the GitHub repo name. Default: `docker-${GitHub Repo Name}-${gar-environment}` |
| `include-tags-in-push` | Boolean | Disables the pushing of tags, and instead includes just a list of images as docker tags. Used when pushing docker digests instead of docker tags. |
| `labels` | String | List of custom labels to add to the image as metadata (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. |
| `load` | Boolean | Whether to load the built image into the local docker daemon (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. |
| `outputs` | String | List of docker output destinations. Passed to `docker/build-push-action`. |
| `platforms` | String | List of platforms to build the image for. Passed to `docker/build-push-action`. |
| `push` | String | Whether to push the image to the configured registries. Passed to `docker/build-push-action`. |
| `registries` | String | CSV list of registries to build images for. Accepted registries are "gar" and "dockerhub". |
| `secrets` | String | Secrets to expose to the build. Only needed when authenticating to private repositories outside the repository in which the image is being built. Passed to `docker/build-push-action`. |
| `ssh` | String | List of SSH agent socket or keys to expose to the build Passed to `docker/build-push-action`. |
| `tags` | String | List of Docker tags to be pushed. Passed to `docker/build-push-action`. |
| `target` | String | Sets the target stage to build. Passed to `docker/build-push-action`. |

## Outputs

| Name | Type | Description |
| -------------- | ------ | ------------------------------------------------------------ |
| `annotations` | String | Generated annotations (from docker/metadata-action) |
| `digest` | String | Image digest (from docker/build-push-action) |
| `imageid` | String | Image ID (from docker/build-push-action) |
| `images` | String | Comma separated list of the images that were built |
| `json` | String | JSON output of tags and labels (from docker/metadata-action) |
| `labels` | String | Generated Docker labels (from docker/metadata-action) |
| `metadata` | String | Build result metadata (from docker/build-push-action) |
| `metadatajson` | String | Metadata JSON (from docker/metadata) |
| `tags` | String | Generated Docker tags (from docker/metadata-action) |
| `version` | String | Generated Docker image version (from docker/metadata-action) |

## How we construct Google Artifact Registry Images

The full GAR image is constructed as follows, where `gar-project` is determined by `inputs.gar-environment`.

"${{ inputs.gar-registry }}/${{ gar-project }}/${{ inputs.gar-repository }}/${{ inputs.gar-image }}"

## How we construct DockerHub Images

The full DockerHub image is constructed as follows:

"${{ inputs.dockerhub-registry }}/${{ inputs.dockerhub-repository }}"

## Adding New Registries

Each registry is setup as follows:

- All inputs for a registry share the same prefix (ex: `gar-image`, `gar-repository`).
- Inputs that are used for a specific registry are _not_ required by the workflow. Instead, validation is done in a step
specific to that registry.
- To calculate which registries have been configured, we loop through `inputs.registries`, and for each registry
configured we set the outputs `include-<registry>`. Those flags can be used to create steps that only execute when X
registry is configured.
- Each registry has a Setup step. This step takes the inputs specific to that registry and generates an untagged,
`image` name for that specific registry.
- The `setup-vars` step then loops through each configured image and creates a full list of images to push.
- That's it! That list of images to push is fed to `docker/build-push-action` along with the configured tags, and each
tagged image is pushed to each registry.

So then the full checklist of work to do to implement a new registry is:

- [ ] Add (and document) any inputs that you need to capture. Use the same prefix for all inputs, and all inputs must
_not_ be required.
- [ ] Add a step before `setup-vars` that takes those input values and constructs a valid untagged image name for the
registry you'll be pushing to. Then set that as an output.
Ex: `echo "image=${DOCKERHUB_REGISTRY}/${DOCKERHUB_IMAGE}" | tee -a "${GITHUB_OUTPUT}"`
- [ ] Add your image into the `setup-vars` step by passing the output image into an env variable, and adding it to the
list of images to be parsed. Use the existing repos as examples.
- [ ] Add a login step that depends
on `${{ inputs.push == 'true' && steps.registries.outputs.include-<yourRegistry> == 'true' }}`, where yourRegistry is
the value that will be passed into the `registries` input. Again, use existing repos as examples.
- [ ] Celebrate
Loading
Loading