Introduction to Metadata-Action
Metadata-Action is a GitHub Action designed to extract metadata from Git references and GitHub events. Its primary purpose is to assist in tagging and labeling Docker images, especially when used in conjunction with the Docker Build Push action.
Overview
The Metadata-Action simplifies the process of managing Docker image metadata by streamlining how tags and labels are generated based on various Git and GitHub contexts. This capability is particularly valuable in Continuous Integration (CI) and Continuous Deployment (CD) pipelines where consistent and meaningful image tagging is crucial.
Key Features
- Extract Metadata: The action pulls information from Git references and GitHub events to generate metadata, including tags and labels.
- GitHub Context Integration: Integrates seamlessly with GitHub workflows, allowing for metadata extraction directly from workflow events, branches, tags, and pull requests.
- Compatibility with Docker Actions: Works in harmony with Docker-specific actions for building, pushing, and labeling Docker images.
- Flexible Tagging Options: Offers various options for tagging, including semantic versioning (semver) and pattern-based tags.
- Customizable Outputs: Allows customization of output labels and tags, enabling precise control over Docker image information.
Usage
Basic Configuration
Here's a typical configuration example for using Metadata-Action in a GitHub workflow:
name: ci
on:
push:
branches:
- 'master'
tags:
- 'v*'
pull_request:
branches:
- 'master'
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Docker meta
id: meta
uses: docker/metadata-action@v5
with:
images: name/app
- name: Login to DockerHub
if: github.event_name != 'pull_request'
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
Semantic Versioning (Semver)
To enhance the tagging scheme using semantic versions, the following configuration can be utilized:
with:
images: name/app
tags: |
type=ref,event=branch
type=semver,pattern={{version}}
Customizing Inputs and Outputs
Metadata-Action supports various input options to tailor the metadata extraction process, such as setting different image names, tag patterns, and context sources. The step outputs include structured tags and labels that can be used further in Docker Bake Actions or similar processes.
Inputs
- context: Specifies whether to source metadata from the workflow's GitHub context or directly from the Git context.
- images: A list of Docker images for base tag naming.
- tags: A list of tag types and patterns to define tagging strategies, with support for semver and scheduled tags.
- flavor: Controls tag and label styling and handling, such as latest tag inclusion.
Outputs
- tags: Generated Docker tags.
- labels: Associated Docker labels.
- json: A JSON object containing all relevant metadata outputs for further processing.
Conclusion
Metadata-Action is a powerful tool that integrates seamlessly with GitHub Actions to automate the generation of meaningful metadata for Docker images. By utilizing this action, developers can maintain a structured and efficient CI/CD pipeline, ensuring consistent image tagging and labeling throughout their deployment processes.