Git Tag Sequencer

Generate a scoped monotonically increasing sequence number as a git tag, scoped by a namespace and optional key. Useful for build numbering, release tagging, run counts within or not tied to full workflow runs, etc.

---

Inputs

Name	Description	Type	Required	Default
namespace	Namespace / "category" for the sequence (e.g., build)	string	yes	—
key	Optional key / "sub-scope" within the namespace; if omitted, namespace is used as the sequence name	string	no	—
root_tag	Optional git tag to use as the commit reference for the new tag; defaults to using current branch HEAD	string	no	—
seed	Starting number if no existing tags found	number	no	1
with_cleanup	Whether to delete previous tags matching the sequence	boolean	no	false
dry_run	Logs actions without creating or deleting tags	boolean	no	false

---

Outputs

Name	Description
sequence	The sequence number assigned
tag	The tag pushed for the sequence

---

Usage

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
      fetch-tags: true

  - name: Get Sequence
    uses: hwrok/git-tag-sequencer@v1
    id: get_sequence
    with:
      namespace: 'build'
      key: '1.2.3'
      with_cleanup: true

  - run: echo "Next sequence: ${{ steps.get_sequence.outputs.sequence }}"

Requirements

• The repository must be checked out with tags fetched (actions/checkout: with: fetch-depth: 0 and fetch-tags: true, or - run: git fetch --tags --prune --unshallow)
• Job requires permissions: contents: write to create and delete tags
• Use dry_run to preview actions without making changes
• Cleanup removes all previous tags matching the sequence, leaving only the newly created tag

Examples

Namespace + Key

with:
  namespace: "build"
  key: "1.2.3"

• tag placed on: current branch HEAD (default)
• example tag created: build-1.2.3-42 (assuming the previous was -41)
• meaning: build number 42 for version 1.2.3

Placing Tag on an Existing "Root Tag" for Easy Reference, Cleanliness, or Disambiguation

with:
  namespace: "deploy"
  key: "staging"
  root_tag: "release-2025"

• tag placed on: commit tagged release-2025
• example tag created: deploy-staging-5
• meaning: 5th deployment to staging for the release tagged release-2025

Simplest Use Case

with:
  namespace: "build"

• tag placed on: current branch HEAD
• example tag created: build-17
• meaning: build number 17 (no additional scoping key)

Re-seeding

with:
  namespace: "build"
  key: "2.0.0"
  seed: 100

• potential use cases
  • migrating from a different sequencing system and want to start where it left off
  • repairing sequence after accidental tag deletions to avoid reusing old numbers
• tag placed on: current branch HEAD
• example tag created: build-2.0.0-100 (if no existing tags ≥ 100 found)