How to Run a Workflow Only on Tags in GitHub Actions

A tags filter on the push event makes a workflow fire only for tag pushes, not branch commits.

Set on.push.tags to a glob such as v*. The workflow ignores branch pushes and runs only when a matching tag arrives.

Steps

• Under on.push, add a tags: glob (e.g. v*.*.*).
• Omit branches: so branch pushes do not trigger this workflow.
• Read the tag from github.ref_name inside the job.

Workflow

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

Gotchas

• A push that creates both a branch and a tag fires once per matching filter.
• Tag globs use the fnmatch syntax, not full regex.

Related guides