Plugins / Docker Tags

Docker Tags

by dvjn

ghcr.io/dvjn/woodpecker-docker-tags-plugin

docker

Plugin to autogenerate tags for building docker images from Git and CI events.

Woodpecker CI plugin to autogenerate tags for building docker images from Git and CI events.

This plugin can be used to autogenerate .tags file for docker build plugins like woodpecker-ci/plugin-kaniko and woodpecker-plugins/docker-buildx

Settings

Name	Default	Description
tags	none	Configuration for generating tags
tags_file	.tags	File to save generated tags

Example

steps:
  - name: generate_docker_tags
    image: ghcr.io/dvjn/woodpecker-docker-tags-plugin
    settings:
      tags: |
        edge
        pr
        semver --auto
        cron --format nightly-%Y%m%d
        sha

`tags` input

This is the main input for this plugin. This is a multiline string. Each line represents a different tag to be applied. Each line is in the form of a cli command.

All the available commands are:

branch
cron
edge
pr
raw
semver
sha
tag

`branch`

Generates tags from branch names for push events.

tags: |
  # minimal
  branch
  # with custom prefix
  branch -p branch-

Options:

Option	Default	Description
`-p`, `--prefix`	empty	Adds a prefix to the branch name.

Examples:

Command	Branch	Output
`branch`	`feature/add-logging`	`feature-add-logging`
`branch -p br-`	`feature/add-logging`	`br-feature-add-logging`

`cron`

Generates datetime based tags on cron events.

tags: |
  # minimal
  cron
  # with custom format
  cron -f %Y-%m-%d

Options:

Option	Default	Description
`-f`, `--format`	`%Y%m%d`	The tag format. This supports GNU/date format. You can find the reference for the format here.

Examples:

Command	Output
`cron`	`20240602`
`cron -f nightly-%Y-%m-%d`	`nightly-2024-06-02`

`edge`

Generates edge tags for the default branch. The edge tag reflects the last commit of the active branch on your Git repository.

tags: |
  # minimal
  edge
  # with custom tag value of "next"
  edge -v next
  # using branch other than the repository default branch
  edge -b dev

Options:

Option	Default	Description
`-v`, `--value`	`edge`	Specifies the value for the tag.
`-b`, `--branch`	repository default	Specifies the branch name.

Examples:

Command	Branch	Output
`edge`	`main`	`edge`
`edge -v latest`	`main`	`latest`
`edge -b dev -v dev`	`dev`	`dev`

`pr`

Generates tag on pull_request event, based on the pull request's id.

tags: |
  # minimal
  pr
  # using custom prefix for tags
  pr -p pull-

Options:

Option	Default	Description
`-p`, `--prefix`	`pr-`	Adds a prefix to the pull request name.

Examples:

Command	Pull Request ID	Output
`pr`	`123`	`pr-123`
`pr -p pull-`	`123`	`pull-123`

`semver`

Generates tags based on semver versions parsed from pushed git tags.

tags: |
  # minimal
  semver
  # generate all standard version tags at once
  semver --auto
  # generate major version tag
  semver -f {{major}}
  # generate major minor version tag
  semver -f {{major}}.{{minor}}

Options:

Option	Default	Description
`-a`, `--auto`	`false`	Generate `major`, `major.minor`, `major.minor.patch`, and `version` tags. Cannot be combined with `--format`.
`-f`, `--format`	`{{version}}`	Specifies the format for the tag.
`-v`, `--value`	commit tag	Specifies the value for the tag.

The format argument supports the following expressions:

{{raw}}: the actual tag
{{version}}: the cleaned up version
{{major}}: major version identifier
{{minor}}: minor version identifier
{{patch}}: patch version identifier

Pre-release handling: When the tag contains a pre-release suffix (e.g., -beta.0, -rc4), only formats using {{version}} or {{raw}} produce output. Partial formats like {{major}} or {{major}}.{{minor}} are skipped to avoid overwriting stable release tags.

For example, semver --auto (or the equivalent four semver --format lines) with a stable tag v1.2.3 produces three unique Docker tags: 1, 1.2, and 1.2.3. With a pre-release tag v1.2.3-rc4 it produces only 1.2.3-rc4. The partial tags are skipped -- including {{major}}.{{minor}}.{{patch}} -- because publishing 1.2.3 for a release candidate would incorrectly indicate a stable release.

Examples:

Command	Tag	Output
`semver`	`v1.2.3`	`1.2.3`
`semver -f {{raw}}`	`v1.2.3`	`v1.2.3`
`semver -f {{version}}`	`v1.2.3`	`1.2.3`
`semver -f ver-{{major}}`	`v1.2.3`	`ver-1`
`semver -f v{{major}}.{{minor}}`	`v1.2.3`	`v1.2`
`semver -f {{patch}}`	`v1.2.3`	`3`
`semver -f {{version}}`	`v1.2.3-rc4`	`1.2.3-rc4`
`semver -f {{raw}}`	`v1.2.3-rc4`	`v1.2.3-rc4`
`semver -f {{major}}.{{minor}}`	`v1.2.3-rc4`	(skipped)
`semver -f {{patch}}`	`v1.2.3-rc4`	(skipped)
`semver --auto`	`v1.2.3`	`1`, `1.2`, `1.2.3`
`semver --auto`	`v1.2.3-rc4`	`1.2.3-rc4`

`raw`

Generates a raw preconfigured tag on any event.

tags: |
  # minimal
  raw -v last-built

Option	Default	Description
`-v`, `--value`	empty	Specifies the value for the tag.

Examples:

Command	Output
`raw -v abcd`	`abcd`

`sha`

Generates tag using the commit SHA.

tags: |
  # minimal
  sha
  # generates tag with full sha
  sha -l
  # use custom prefix for sha tag
  sha -p commit-

Options:

Option	Default	Description
`-l`, `--long`	`false`	Use the full 40 character SHA.
`-p`, `--prefix`	`sha-`	Adds a prefix to the SHA.

Examples:

Command	Output
`sha`	`sha-abcdef12`
`sha -l`	`sha-abcdef1234567890abcdef1234567890abcdef12`
`sha -p commit-`	`commit-abcdef12`

`tag`

Generates tag from pushed git tag.

tags: |
  # minimal
  tag

Examples:

Command	Tag	Output
`tag`	`v1.0.0`	`v1.0.0`

Notes

Tag Sanitization

All the values are converted to lowercase.
All the values apart from alphabets, numbers, hyphen (-), underscore (_) and period (.) are replaces with a hyphen.
The length of the tag is truncated to 128 characters.

Common Use Cases

Simple Project with Versioned Releases

Basic setup for a project that tags releases and builds on every push.

steps:
  - name: generate_tags
    image: ghcr.io/dvjn/woodpecker-docker-tags-plugin
    settings:
      tags: |
        sha
        semver --auto

Tags generated:

Push: sha-abc123
Tag v1.2.3: 1, 1.2, 1.2.3.

CI/CD Pipeline with PR Previews

Full CI flow: preview builds for PRs, edge for main branch, versioned releases.

steps:
  - name: generate_tags
    image: ghcr.io/dvjn/woodpecker-docker-tags-plugin
    settings:
      tags: |
        pr
        edge
        semver --auto

Tags generated:

PR #123: pr-123
Push to main: edge
Tag v1.2.3: 1, 1.2, 1.2.3
Tag v1.2.3-rc4: 1.2.3-rc4 (partial tags skipped)

Multi-Environment Setup

Separate tags for dev, staging, and production environments using branch names.

steps:
  - name: generate_tags
    image: ghcr.io/dvjn/woodpecker-docker-tags-plugin
    settings:
      tags: |
        branch -p env-
        sha

Tags generated:

Push to dev: env-dev, sha-abc123
Push to staging: env-staging, sha-abc123
Push to production: env-production, sha-abc123

Nightly Builds

Generate dated tags for scheduled builds via cron.

steps:
  - name: generate_tags
    image: ghcr.io/dvjn/woodpecker-docker-tags-plugin
    settings:
      tags: |
        cron -f nightly-%Y-%m-%d

Tags generated on cron event:

nightly-2024-06-02

Minimal / Lean Setup

For projects that only need basic tags.

steps:
  - name: generate_tags
    image: ghcr.io/dvjn/woodpecker-docker-tags-plugin
    settings:
      tags: |
        edge
        sha
        semver

Tags generated:

Push to main: edge, sha-abc123
Tag v1.2.3: 1.2.3 (no partial tags)

Preview Builds Only

Useful for development/testing where you only need PR previews.

steps:
  - name: generate_tags
    image: ghcr.io/dvjn/woodpecker-docker-tags-plugin
    settings:
      tags: |
        pr
        branch

Tags generated:

PR #42: pr-42
Push to feature/login: feature-login

Docker Tags

Settings

Example

tags input

branch

cron

edge

pr

semver

raw

sha

tag

Notes

Tag Sanitization

Common Use Cases

Simple Project with Versioned Releases

CI/CD Pipeline with PR Previews

Multi-Environment Setup

Nightly Builds

Minimal / Lean Setup

Preview Builds Only

`tags` input

`branch`

`cron`

`edge`

`pr`

`semver`

`raw`

`sha`

`tag`