Docker Tags Action

• Inputs
  • Tags
  • Labels
• Outputs
• Examples
• Tags
• Support
• Contributing

Generate Docker Tags and Labels for building Docker images with GitHub Actions.

For a more detailed implementation see: https://github.com/docker/metadata-action

Note

Please submit a Feature Request for new features or Open an Issue if you find any bugs.

Inputs

Input	Default Value	Description of the Input Value
images	ghcr.io/${{ github.repository }}	Images for Tag Generation, CSV or Newline
tags	see tags	Extra Tags to Generate, CSV or Newline
labels	see labels	Extra Labels to Generate, CSV or Newline
seperator	\n	Output Seperator
latest	default	Latest Tag: [true, false, default]
summary	true	Add Summary to Job

This works with no inputs, but you can customize the resulting tags and labels with inputs.

- name: 'Docker Tags'
  id: tags
  uses: cssnr/docker-tags-action@v2

seperator

Output seperator. Newline is default and that works as the input for the docker build actions.

latest

Default behavior only adds latest tag to a release that are not a pre-release.

summary

Write a Summary for the job. To disable this set to false.

👀 View Example Summary

---

Generated 2 Tags and 8 Labels for 1 Images. Parsed ref: pr-6

Docker Tags

ghcr.io/cssnr/docker-tags-action:pr-6
ghcr.io/cssnr/docker-tags-action:latest

Docker Labels

org.opencontainers.image.created=2025-02-20T02:33:28.010Z
org.opencontainers.image.revision=fb2319bda85e745c78981bc0ec6b316f07b602b5
org.opencontainers.image.source=https://github.com/cssnr/docker-tags-action
org.opencontainers.image.title=docker-tags-action
org.opencontainers.image.url=https://github.com/cssnr/docker-tags-action
org.opencontainers.image.version=pr-6
org.opencontainers.image.description=Generate Docker Tags and Labels for building Docker images with GitHub Actions.
org.opencontainers.image.authors=smashedr

Inputs

Input	Value
images	ghcr.io/cssnr/docker-tags-action
tags
labels	org.opencontainers.image.licenses=,org.opencontainers.image.authors=smashedr
seperator	"\n"
latest	true
summary	true

---

To view a workflow run, click on a recent Test job (requires login).

docker tags

Event	Ref	Tags
tag / release	refs/tags/v1.0.0	v1.0.0
push / other	refs/heads/master	master
pull_request	refs/pull/1/merge	pr-1

This is the default tag added which is also set as the version for the label.

Coming Soon: Add an option called default to disable or override the default tag.

docker labels

org.opencontainers.image.description=Example Repository Description
org.opencontainers.image.revision=32b96cee5b4e940b4023f78261702470d59c8001
org.opencontainers.image.source=https://github.com/cssnr/docker-tags-action
org.opencontainers.image.title=repository-name
org.opencontainers.image.url=https://github.com/cssnr/docker-tags-action
org.opencontainers.image.version=v1.0.0
org.opencontainers.image.licenses=GPL-3.0

These are the default labels. You can add them or remove them by providing a key with no value.

The description and license are only added if they are defined on your repository.

Example removing org.opencontainers.image.licenses and adding org.opencontainers.image.authors.

labels: |
  org.opencontainers.image.licenses=
  org.opencontainers.image.authors=smashedr

Outputs

Output	Output Description
tags	Generated Tags
labels	Generated Labels
annotations	Generated Annotations

All outputs are seperated by the inputs seperator which defaults to a newline.

- name: 'Docker Tags'
  id: tags
  uses: cssnr/docker-tags-action@v2

- name: 'Echo Result'
  run: |
    echo -e "tags: \n${{ steps.tags.outputs.tags }}"
    echo -e "labels: \n${{ steps.tags.outputs.labels }}"
    echo -e "annotations: \n${{ steps.tags.outputs.annotations }}"

Examples

With all inputs:

- name: 'Docker Tags'
  id: tags
  uses: cssnr/docker-tags-action@v2
  with:
    images: 'ghcr.io/${{ github.repository }}'
    tags: v1,v1.0
    labels: |
      org.opencontainers.image.licenses=
      org.opencontainers.image.authors=smashedr
    seperator: ','
    latest: true

Full Example:

name: 'Release'

on:
  release:
    types: [published]

jobs:
  build:
    name: 'Build'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      packages: write

    steps:
      - name: 'Checkout'
        uses: actions/checkout@v4

      - name: 'Docker Tags'
        id: tags
        uses: cssnr/docker-tags-action@v2
        with:
          images: 'ghcr.io/${{ github.repository }}'
          tags: ${{ github.ref_name }}
          latest: false

      - name: 'Echo Tags'
        run: |
          echo -e "tags: \n${{ steps.tags.outputs.tags }}"
          echo -e "labels: \n${{ steps.tags.outputs.labels }}"

      - name: 'Docker Login'
        uses: docker/login-action@v3
        with:
          registry: 'ghcr.io'
          username: ${{ vars.GHCR_USER }}
          password: ${{ secrets.GHCR_PASS }}

      - name: 'Setup Buildx'
        uses: docker/setup-buildx-action@v3

      - name: 'Build and Push'
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.tags.outputs.tags }}
          labels: ${{ steps.tags.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

To see this used in a release workflow, see: https://github.com/cssnr/cloudflare-purge-cache-action/blob/master/.github/workflows/release.yaml

For more examples, you can check out other projects using this action:
https://github.com/cssnr/docker-tags-action/network/dependents

Tags

The following rolling tags are maintained.

Version Tag	Rolling	Bugs	Feat.	Name	Target	Example
	✅	✅	✅	Major	vN.x.x	vN
	✅	✅	❌	Minor	vN.N.x	vN.N
	❌	❌	❌	Micro	vN.N.N	vN.N.N

You can view the release notes for each version on the releases page.

The Major tag is recommended. It is the most up-to-date and always backwards compatible. Breaking changes would result in a Major version bump. At a minimum you should use a Minor tag.

Support

For general help or to request a feature, see:

• Q&A Discussion: https://github.com/cssnr/docker-tags-action/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/docker-tags-action/discussions/categories/feature-requests

If you are experiencing an issue/bug or getting unexpected results, you can:

• Report an Issue: https://github.com/cssnr/docker-tags-action/issues
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY
• Provide General Feedback: https://cssnr.github.io/feedback/

For more information, see the CSSNR SUPPORT.md.

Contributing

If you would like to submit a PR, please review the CONTRIBUTING.md.

Please consider making a donation to support the development of this project and additional open source projects.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy Action
• Docker Context Action
• Actions Up Action
• VirusTotal Action
• Mirror Repository Action
• Update Version Tags Action
• Docker Tags Action
• Update JSON Value Action
• JSON Key Value Check Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Package Changelog Action
• NPM Outdated Check Action
• Label Creator Action
• Algolia Crawler Action
• Upload Release Action
• Check Build Action
• Web Request Action
• Get Commit Action

❔ Unpublished Actions

These actions are not published on the Marketplace, but may be useful.

• cssnr/create-files-action - Create various files from templates.
• cssnr/draft-release-action - Keep a draft release ready to publish.
• cssnr/env-json-action - Convert env file to json or vice versa.
• cssnr/push-artifacts-action - Sync files to a remote host with rsync.
• smashedr/update-release-notes-action - Update release notes.
• smashedr/combine-release-notes-action - Combine release notes.

---

📝 Template Actions

These are basic action templates that I use for creating new actions.

• js-test-action - JavaScript
• ts-test-action - TypeScript
• py-test-action - Python (Dockerfile)
• docker-test-action - Docker (Image)

Note: The docker-test-action builds, runs and pushes images to GitHub Container Registry.

---

For a full list of current projects visit: https://cssnr.github.io/