metadata-action/README.md
CrazyMax 6cc07472c0
Generate latest tag by default on push tag event (#5)
Co-authored-by: CrazyMax <crazy-max@users.noreply.github.com>
2020-10-28 17:25:31 +00:00

9.2 KiB

GitHub release GitHub marketplace Test workflow Codecov Become a sponsor Paypal Donate

About

GitHub Action to extract metadata (tags, labels) for Docker. This action is particularly useful if used with Docker Build Push action.

If you are interested, check out my other :octocat: GitHub Actions!

Screenshot


Features

Overview

Event Ref Commit SHA Docker Tags
schedule refs/heads/master 45f132a sha-45f132a, nightly
pull_request refs/pull/2/merge a123b57 sha-a123b57, pr-2
push refs/heads/master cf20257 sha-cf20257, master
push refs/heads/my/branch a5df687 sha-a5df687, my-branch
push tag refs/tags/v1.2.3 bf4565b sha-bf4565b, v1.2.3, latest
push tag refs/tags/mytag afb7833 sha-afb7833, mytag

Usage

name: ci

on:
  schedule:
    - cron: '0 10 * * *' # everyday at 10am
  push:
    branches:
      - '**'
    tags:
      - 'v*.*.*'
  pull_request:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v2
      -
        name: Docker meta
        id: docker_meta
        uses: crazy-max/ghaction-docker-meta@v1
        with:
          images: name/app
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v1
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      -
        name: Login to DockerHub
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v1 
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        uses: docker/build-push-action@v2
        with:
          context: .
          file: ./Dockerfile
          platforms: linux/amd64,linux/arm64,linux/386
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.docker_meta.outputs.tags }}
          labels: ${{ steps.docker_meta.outputs.labels }}

Customizing

inputs

Following inputs can be used as step.with keys

Name Type Description
images List/CSV List of Docker images to use as base name for tags
tag-sha Bool Add git short SHA as Docker tag (default false)
tag-edge Bool Enable edge branch tagging (default false)
tag-edge-branch String Branch that will be tagged as edge (default repo.default_branch)
tag-match String RegExp to match against a Git tag and use first match as Docker tag
tag-match-group Number Group to get if tag-match matches (default 0)
tag-match-latest Bool Set latest Docker tag if tag-match matches (default true)
tag-schedule String Template to apply to schedule tag (default nightly)
sep-tags String Separator to use for tags output (default \n)
sep-labels String Separator to use for labels output (default \n)

List/CSV type can be a newline or comma delimited string

outputs

Following outputs are available

Name Type Description
version String Generated Docker image version
tags String Generated Docker tags
labels String Generated Docker labels

Notes

Latest tag

Latest Docker tag will be generated by default on push tag event. So if for example you push the v1.2.3 Git tag, you will have at the output of this action the Docker tags v1.2.3 and latest. But you can allow the latest tag to be generated only if the Git tag matches a regular expression with the tag-match input.

tag-match examples

Git tag tag-match tag-match-group Docker tag
v1.2.3 \d{1,3}.\d{1,3}.\d{1,3} 0 1.2.3
v2.0.8-beta.67 v(.*) 1 2.0.8-beta.67
v2.0.8-beta.67 v(\d.\d) 1 2.0
release1 \d{1,3}.\d{1,3} 0 release1
20200110-RC2 \d+ 0 20200110

Schedule tag

tag-schedule is specially crafted input to support Handlebars template with the following expressions:

Expression Example Description
{{date 'format'}} {{date 'YYYYMMDD'}} > 20200110 Render date by its moment format

You can find more examples in the CI workflow.

Overwrite labels

If some of the OCI Image Format Specification labels generated are not suitable, you can overwrite them like this:

      -
        name: Build and push
        uses: docker/build-push-action@v2
        with:
          context: .
          file: ./Dockerfile
          platforms: linux/amd64,linux/arm64,linux/386
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.docker_meta.outputs.tags }}
          labels: |
            ${{ steps.docker_meta.outputs.labels }}
            org.opencontainers.image.title=MyCustomTitle
            org.opencontainers.image.description=Another description
            org.opencontainers.image.vendor=MyCompany            

Keep up-to-date with GitHub Dependabot

Since Dependabot has native GitHub Actions support, to enable it on your GitHub repo all you need to do is add the .github/dependabot.yml file:

version: 2
updates:
  # Maintain dependencies for GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬 You can also support this project by becoming a sponsor on GitHub 👏 or by making a Paypal donation to ensure this journey continues indefinitely! 🚀

Thanks again for your support, it is much appreciated! 🙏

License

MIT. See LICENSE for more details.