How to Trigger a Workflow on a Tag Push in GitHub Actions

A tags filter on the push event fires only when a matching tag is pushed, not on ordinary branch commits.

Set on.push.tags to a glob like v*.*.*. Omit branches so branch pushes never trigger it, and read the tag name from github.ref_name.

Steps

• Add tags: under on.push with a version glob.
• Leave out branches: so only tag pushes fire the run.
• Reference the tag with github.ref_name inside jobs.

Workflow

on:
  push:
    tags:
      - 'v*.*.*'
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Building release ${{ github.ref_name }}"

Gotchas

• Pushing a lightweight tag and a branch in one push can fire multiple matching workflows.
• Tag globs are fnmatch, not regex, so v[0-9]+ will not work; use v* style patterns.

Related guides