Q: How do you trigger a pipeline only when a tag is pushed?
GitHub Actions: on: push: tags: ['v']. GitLab: rules: - if: $CI_COMMIT_TAG.
Want to master this scenario in a live sandbox? KodeKloud's Enterprise GitOps with ArgoCD & Kubernetes Rollouts covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: To <strong>trigger a pipeline only when a tag is pushed</strong>, filter on tag refs: in GitHub Actions use <code>on.push.tags</code>, in GitLab CI use <code>rules: - if: $CI_COMMIT_TAG</code>, and in Jenkins use <code>when { buildingTag() }</code>. Release automation depends on this, because a tag is an immutable marker of a version. Interviewers ask to test whether you know the syntax and the gotchas: glob versus regex patterns, tags created by the default token not triggering workflows, and ensuring a tag came from a protected branch.
Mental model: a tag push is its own event
A tag is a ref under refs/tags/, so CI systems can distinguish it from a branch push.
- Event types: Pushing a commit to a branch and pushing a tag are separate push events with different refs.
- Pattern language: GitHub uses glob patterns such as
v*.*.*, not full regex; GitLab can use regex with$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/. - Intent: Tag pipelines are typically release pipelines: build, sign, publish artifacts, create a release.
- Separation: Keep normal branch CI on branch events and put publishing only in the tag workflow.
- Annotated versus lightweight: Annotated tags (
git tag -a) store an author, date and message, which is useful for release notes; both kinds trigger tag pipelines.
Hands-on: trigger a pipeline only when a tag is pushed
Configuration for GitHub Actions, GitLab CI and Jenkins.
# GitHub Actions
on:
push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+'
# no 'branches:' key, so branch pushes do not trigger this workflow
# GitLab CI
release:
rules:
- if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
script: ./release.sh
# Jenkinsfile (declarative)
# stage('Release') {
# when { buildingTag() }
# steps { sh './release.sh' }
# }
git tag -a v1.4.2 -m "Release 1.4.2"
git push origin v1.4.2
- GitHub Actions: Specify
tagsunderpushand nobranchesso only tag pushes run. - GitLab CI: Use
ruleswith$CI_COMMIT_TAG; the variable is only set for tag pipelines. - Jenkins: In a multibranch pipeline enable tag discovery and add
when { buildingTag() }ortag pattern: 'v*', comparator: 'GLOB'. - Create the tag: Use an annotated tag and push it explicitly.
- Shallow clones: Tag pipelines may need full history for changelogs. Set
fetch-depth: 0inactions/checkout@v4when you generate release notes.
Verify only tags trigger it
Prove both the positive and negative cases.
gh run list --workflow release.yml --limit 5
git ls-remote --tags origin | tail -3
- Positive test: Push
v1.4.2and confirm a run appears with the refrefs/tags/v1.4.2; in GitHub usegh run list --workflow release.yml. - Negative test: Push a commit to
mainand a tag liketest-1; neither should start the release workflow. - Inspect context: Print
github.ref_nameor$CI_COMMIT_TAGin the first step so logs show which tag fired it. - Boundary cases: Confirm
v1.10.0matches, and decide deliberately whether pre-releases such asv1.4.2-rc1should trigger the release workflow or a separate one. - Deleting tags: Deleting a tag does not cancel a running pipeline; cancel the run manually if the tag was pushed by mistake.
Failure modes and gotchas
Most surprises are about who pushes the tag and where it points.
- Default token does not trigger: A tag pushed using
GITHUB_TOKENinside a workflow will not start another workflow. Use a GitHub App token or a dedicated PAT, or call the release workflow withworkflow_call. - Tag on the wrong commit: Anyone with write access can tag any commit. Verify in the pipeline that the tagged commit is reachable from
mainusinggit merge-base --is-ancestor. - Branch and tag both match: If a workflow lists both
branchesandtags, either event triggers it; omit branches if you want tags only. - Moving tags: Force-pushing a tag re-triggers or confuses releases. Treat release tags as immutable and protect them.
- Duplicate runs: If a tag is pushed with a branch in the same
git push, both events fire; keep release logic in the tag-only workflow and keep tests in the branch workflow.
Production practice
Make tag-driven releases safe and repeatable.
- Protected tags: Use tag protection or repository rulesets so only maintainers can create
v*tags. - Derive versions from the tag: Set the image tag and chart version from the tag name so there is no second source of truth.
- Environment approvals: Gate production deployment with environment protection rules even though the tag triggered the build.
- Automate tagging: Tools like release-please or semantic-release create the tag after merging, which removes manual mistakes.
- Idempotent publishing: Make release steps safe to re-run, for example by skipping a push when the image tag already exists, because tag pipelines are retried after transient failures. Audit trail: Create a GitHub or GitLab release from the tag with generated notes so each version links to the commits, pipeline run and artifacts.
- To trigger only on tags, filter on tag refs: on.push.tags in GitHub Actions, rules with CI_COMMIT_TAG in GitLab, buildingTag in Jenkins.
- I test the positive case with a real tag and the negative case with branch pushes and non-matching tags.
- I automate tagging with release tooling, protect the tag namespace and derive versions from the tag.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Listing both branches and tags in the trigger Either event starts the workflow, so release steps run on ordinary pushes.
- Creating the tag with GITHUB_TOKEN and expecting a run Events caused by the default token do not start new workflows.
- Using full regex syntax in a GitHub tag filter GitHub filters use glob-style patterns, so constructs like \d are not understood and the workflow never fires.
- Allowing anyone to push release tags A tag on an unreviewed commit publishes unreviewed code.