How to set org.opencontainers.image.version with git sha?

[felipecrs]

I'm calling the action with:

      - name: Docker meta
        uses: docker/metadata-action@v5
        with:
          images: |
            ghcr.io/${{ github.repository_owner }}/devcontainer
          labels: |
            org.opencontainers.image.title=Devcontainer
            org.opencontainers.image.description=A multi-purpose Docker on Docker or Docker in Docker image to be used as a Devcontainer.
          flavor: |
            latest=false
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=sha,enable=${{ github.event_name == 'push' }}
            type=raw,value=latest,enable=${{ github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}

And on push: [branch: [master]], this is generating the label as:

org.opencontainers.image.version: master

Which is pretty much useless. I would like the org.opencontainers.image.version to be generated with the same value as the type=sha tag:

org.opencontainers.image.version: sha-ee426c9

Any ideas to accomplish it? Maybe that should even be the default value when tags has type=sha and no semver is available?

[polarathene]

Quick answer

Implicitly via tags input, set priority above all defaults:

type=sha,enable=${{ github.event_name == 'push' }},priority=999

Be explicit:

# Image config stores labels:
labels: |
  org.opencontainers.image.revision=sha-${{ github.sha }}

# Image index/manifest annotations are useful for queries/filters when interacting with a registry:
annotations: |
  org.opencontainers.image.revision=sha-${{ github.sha }}

---

Long answer

This is an easy mistake (I've made it myself), but it is actually explained in the docs (just easy to miss), it's due to the action assigning priority values to different types which will sort your tags by priority and the first tag processed (enabled) from that list will become the primary image version.

In your case, type=sha is the lowest and type=ref is the highest. So the appropriate type=ref is selected for the version.

metadata-action/README.md

Lines 808 to 810 in ed95091

	| `ref` | `600` |
	| `raw` | `200` |
	| `sha` | `100` |

You can always prioritize your type=sha entry by adding the priority attribute:

type=sha,enable=${{ github.event_name == 'push' }},priority=999

If there's multiple tags with the same priority value, it will be the first one you defined of that priority (the sorting won't mess with your declaration order of same priority), if you would like more control over that or the default priority assigned for that tag entry type is too low, you can set a higher priority manually.

More details here if you need a technical deep-dive to understand implementation: #587 (comment)

---

Alternatively, if you don't need that sha- prefix, you can more clearly express this like:

labels: |
  org.opencontainers.image.revision=${{ github.sha }}

or add the sha- prefix explicitly:

labels: |
  org.opencontainers.image.revision=sha-${{ github.sha }}

Remember to do the same if you also use annotations output for your image index/manifests. Or just use the priority approach for this to be implicit (sometimes convenient, but being explicit avoids issues like you've run into entirely).

[felipecrs]

Bumping the priority works like a charm, thanks a lot @polarathene!

[polarathene]

Off-topic - Feedback / Questions on your other tag types

Your raw latest tag is checking if the github.ref is the default branch. There is a {{ is_default_branch }} expression provided by the action that you could use which would be a bit more terser.

I'm not sure if you can use it within ${{ ... }} (I don't think so), but skipping the push event condition should be ok here:

type=raw,value=latest,enable={{ is_default_branch }}

• type=sha would still be valid alongside it (along with any other branches triggering the workflow via push event + type=ref).
• type=ref with the branch event will still publish the separate branch name tag, and for other branches or the PR event these won't be the default branch, so no worries about accidentally introducing a latest there either.

I don't believe a tag event would be considered the default branch either (if you were to later add that).

---

I'd be interested in understanding the value of the sha tag publishing?:

• Do you find that useful with your project to have tags for images associated to type=ref,event=branch?
• Or is it often temporary for CI purposes (such as rerunning a workflow that would pull by the sha tag instead of branch/latest tag?)

Likewise, bit curious about type=ref,event=pr?:

• Is that for PRs made by first-party contributors? (I think their PRs may have access to secrets, or that might be specific to branches on the main repo not a fork of theirs that they open a PR for)
• To my knowledge for third-party contributors, they're able to manipulate untrusted workflows (like those that would trigger by a pull request event), so secrets are not available for pushing an image to a registry (as the contributor could steal them, along with run a build to publish malware, etc), hence I'm not sure how it's useful for PRs when it'd be inconsistent depending on the PR author 😅

Any insights to how those tags are useful would be great for me to know 😁

[felipecrs]

This also works great, and is a nice simplification. Thanks!