simple-tag-release

Set a tag on the current commit and optionally cut a GitHub release. You supply the exact tag; the action points it at the current commit and refreshes the release. It does not bump versions, edit manifests, or commit. Made for versioning action repositories, where a floating major tag (v1) is re-pointed as the code moves on.

What it does

Runs against the commit the calling workflow is on, through the REST API - no checkout, no push:

1. validates the tag name;
2. sets it on the current commit, creating it or force-moving it if it exists;
3. if release is true, deletes any existing release for the tag and recreates it with generated notes.

A re-run is idempotent: the tag re-points to the same commit and the release is recreated, so there is no "do not re-run" hazard.

The tag lands on github.sha, so trigger the action from workflow_dispatch or push - on pull_request that value is a synthetic merge commit.

Usage

name: release

on:
  workflow_dispatch:
    inputs:
      tag:
        description: "Tag to set/move"
        type: string
        default: "v1"

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: voidmason/simple-tag-release@v1
        with:
          tag: ${{ inputs.tag }}

No checkout step is needed: the action operates on the current commit through the API. permissions: contents: write is required - the tag and the release are written with the workflow token.

Inputs

Input	Required	Default	Description
tag	yes	-	Tag to set on the current commit (v1, v1.2.3). Force-moved if it exists.
release	no	true	Create/refresh a GitHub release for the tag. false only moves the tag.
token	no	workflow token	Token with contents: write.

Outputs

Output	Description
tag	The tag that was set.
sha	The commit the tag now points at.

Token

Defaults to the workflow GITHUB_TOKEN. contents: write is enough - the action only writes a tag and a release through the API and never pushes to a branch. A tag written with GITHUB_TOKEN does not trigger downstream workflows, which does not matter for publishing an action. Pass your own token if you need a different release author or a tag that triggers downstream runs.

Immutable releases

The default model here - a release on a floating v1 that gets moved - works only while immutable releases are off (they are opt-in, off by default). Once immutable releases are enabled on the repository or organization, a published release locks its tag to a commit: the tag can no longer be moved and the force-move fails with a 422. Keep floating tags release-less then (release: false) and cut releases on fixed version tags instead.

Requirements

The runner needs gh and git; ubuntu-latest ships both.

License

MIT, see LICENSE.