README.org

Automate GitTags to Workflow Options

What is this project

The idea to create this project was born from this discussion, where some people raised the desire to automate the process of defining the options for a workflow dispatch with the current tags from their repository.

Since GitHub does not offer this feature, I decided to create it myself. You can read an article from my blog explaining how it works here.

Usage example

name: On tag creation

on:
  workflow_dispatch:
  push:
    tags: # https://github.com/orgs/community/discussions/25302
    - '*'

jobs:
  custom-action:
    name: Update workflow dispatch tags
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        files: [example-001.yml]
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # to get the tags
      - name: Get the repository tags
        run: |
          THIS_GIT_TAGS=$(git tag --sort -creatordate | tr '\n' ' ')

          echo "Git tags: ${THIS_GIT_TAGS}"

          echo "THIS_GIT_TAGS=${THIS_GIT_TAGS}" >> "${GITHUB_ENV}"
      - name: Run custom action
        uses: FsharpGHActions/git-tag-to-workflow-dispatch@master
        with:
          values-to-take: 5
          workflow-file-name: ${{ matrix.files }}
          workflow-yaml-key: 'version'
          pull-request: true
          # needs to be a PAT to update the workflows/ folder
          github-token: ${{ secrets.PAT_GITHUB }}
          git-tags: ${{ env.THIS_GIT_TAGS }}
          base: 'main'

How to use it?

Required input arguments

Input	Description	Default value
values-to-take	Let you specify how many tags to take.	-1
workflow-file-name	Target workflow file name that must live under `.github/workflows/`.
workflow-yaml-key	Specify the workflow YAML key that will be updated.
github-token	PAT token with more information at Personal Access Token - PAT.
git-tags	The repository tags from the newest to the oldest. Example Extract the tags.
base	Sets the pull request base branch. Usually it’s ‘main’ or ‘master’.

Optional input arguments

Input	Description	Default value
pull-request	TODO. If ‘true’, create a PR; if false, commit directly.	‘true’

Personal Access Token - PAT

Since this action creates a PR automatically that changes the contents of the repository workflows, it demands some special permissions, which are out of the scope of the GITHUB_TOKEN (the community discussion).

My recommendation is that you create a Fine-grained Personal Access Token with access only to the repositories you intend to use this action, and with permissions:

• Read access to metadata (this is enabled by default);
• Read and write access to code;
• Read and write access to pull requests;
• Read and write access to workflows.

Extracting the tags

Since there are many ways to extract the tags from the repository, I decided to not add this feature to the project, so you’re free to decide which one to use. For my examples, I use basically this approach:

jobs:
  custom-action:
    name: Update workflow dispatch tags
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # to get the tags
      - name: Get the repository tags
        run: |
          THIS_GIT_TAGS=$(git tag --sort -creatordate | tr '\n' ' ')

          echo "Git tags: ${THIS_GIT_TAGS}"

          echo "THIS_GIT_TAGS=${THIS_GIT_TAGS}" >> "${GITHUB_ENV}"
          # then you can use this environment variable when calling
          # the custom action

Feel free to add your personal approach to this documentation.