Annotations let you specify arbitrary metadata for OCI image components, such as manifests, indexes, and descriptors.
Add annotations with GitHub Builder
Use Docker GitHub Builder with
set-meta-annotations: true to apply annotations generated by the metadata
action. Use meta-annotations to override generated values while preserving
the other metadata. This example adds a custom description to the final image
index:
name: ci
on:
push:
jobs:
build:
uses: docker/github-builder/.github/workflows/build.yml@v1
permissions:
contents: read
id-token: write
with:
output: image
push: true
set-meta-annotations: true
meta-annotations: |
org.opencontainers.image.description=My application
meta-images: user/app
secrets:
registry-auths: |
- registry: docker.io
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}Add annotations with individual actions
To add annotations when building images with GitHub Actions, use the
metadata-action to automatically create OCI-compliant annotations. The
metadata action creates an annotations output that you can reference, both
with build-push-action and bake-action.
name: ci
on:
push:
env:
IMAGE_NAME: user/app
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Login to Docker Hub
uses: docker/login-action@v4
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4
- name: Extract metadata
id: meta
uses: docker/metadata-action@v6
with:
images: ${{ env.IMAGE_NAME }}
- name: Build and push
uses: docker/build-push-action@v7
with:
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
push: truename: ci
on:
push:
env:
IMAGE_NAME: user/app
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Login to Docker Hub
uses: docker/login-action@v4
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4
- name: Extract metadata
id: meta
uses: docker/metadata-action@v6
with:
images: ${{ env.IMAGE_NAME }}
- name: Build
uses: docker/bake-action@v7
with:
files: |
./docker-bake.hcl
cwd://${{ steps.meta.outputs.bake-file-tags }}
cwd://${{ steps.meta.outputs.bake-file-annotations }}
push: trueConfigure annotation level
With individual actions, annotations are placed on image manifests by default.
To configure the
annotation level, set
the DOCKER_METADATA_ANNOTATIONS_LEVELS environment variable on the
metadata-action step to a comma-separated list of all the levels that you
want to annotate. For example, setting DOCKER_METADATA_ANNOTATIONS_LEVELS to
index results in annotations on the image index instead of the manifests.
The following example creates annotations on both the image index and manifests.
name: ci
on:
push:
env:
IMAGE_NAME: user/app
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Login to Docker Hub
uses: docker/login-action@v4
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4
- name: Extract metadata
id: meta
uses: docker/metadata-action@v6
with:
images: ${{ env.IMAGE_NAME }}
env:
DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
- name: Build and push
uses: docker/build-push-action@v7
with:
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
push: trueNoteThe build must produce the components that you want to annotate. For example, to annotate an image index, the build must produce an index. If the build produces only a manifest and you specify
indexorindex-descriptor, the build fails.