simple-release

Opinionated, customizable GitHub Action to publish releases out of pushed v* tags.

This is a generalization that collects patterns from the workflows used in Quarkdown and other personal projects from my past decade in OSS.

What it does

Each feature is opt-in.

• Tagged release: publishes the release with a composed body and artifacts.

• Version-file bump: writes the tag into a file like version.txt readable by downstream tools, such as build scripts or --version flags.

• Changelog update and extraction: extracts the [Unreleased] section in a keep-a-changelog file, turns it into a dated release section, and uses it to compose the release body.

• Release notes extraction: extracts the notes for the current tag from the changelog.

• Devbuild prerelease: moves a rolling tag to the current commit and publishes a prerelease with attached artifacts as a nightly build.

• Major-version tag alias: extracts and pushes the major from the tag (v2.3.4 → v2), ideal for pinning versions in GitHub Actions (dogfooded in this very action).

Quick start

Publish a release when a tag is pushed

name: Release
on:
  push:
    tags: ['v*']

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: iamgio/simple-release@v1
        with:
          version-file: version.txt
          changelog-file: CHANGELOG.md
          commit: 'true'
          release-files: |
            build/dist/*.zip
            build/dist/*.tar.gz

Publish a rolling devbuild on every main push

name: Devbuild
on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  devbuild:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: iamgio/simple-release@v1
        with:
          devbuild-tag: latest
          devbuild-files: build/dist/*.zip

Release a reusable GitHub Action (major-tag alias)

The following lets a push of a v2.3.4 tag publish a release and force-move the v2 tag to the same commit:

name: Release
on:
  push:
    tags: ['v*.*.*']

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: iamgio/simple-release@v1
        with:
          release: 'true'
          major-tag: 'true'

Inputs

Core

Input	Default	Description
tag	github.ref_name	Tag for the release.
token	github.token	Token used to create the releases.
committer-token	Falls back to token	Token for pushing commits and moving tags. Use a PAT if needed.

Version file

Input	Default	Description
version-file	''	Path to a file to overwrite with the version. Leave empty to skip.
keep-v-prefix	false	When true, writes the tag verbatim. Otherwise strips the leading v.

Changelog

Input	Default	Description
changelog-file	''	Path to a keep-a-changelog file. Leave empty to skip.
update-changelog	true	Turn [Unreleased] into a dated release section.
extract-release-notes	true when changelog set and releasing	Extract release notes for the tag from the changelog into the release-notes output.

Extra body section

Input	Default	Description
body-append-file	''	If set and the file exists, its content is appended after the release notes in the release body.

Release-notes spacers

Input	Default	Description
insert-changelog-spacers	false	When true, inserts a   spacer line before every H2 and H3 heading in the extracted release notes.

Commit back

Input	Default	Description
commit	false	Commit the modified version-file and changelog-file back to a branch.
commit-message	chore: release {tag}	{tag} is substituted with the tag.
commit-user-name	github-actions	Name used for the auto-commit author.
commit-user-email	github-actions[bot]@users.noreply.github.com	Email used for the auto-commit author.
commit-branch	main	Branch to push the commit to.

Devbuild

Input	Default	Description
devbuild-tag	''	Name of the rolling tag to force-move to this commit (e.g. latest). Leave empty to skip.
devbuild-name	Development build	Display name for the prerelease.
devbuild-files	''	Newline- or comma-separated glob patterns of files to attach.

Tagged release

Input	Default	Description
release	auto	auto = create when ref is a tag. Use true/false to force behavior.
release-name	Tag name	Release display name.
release-body	Composed	Literal Markdown body. If empty, composed from release notes and the append file.
release-files	''	Newline- or comma-separated glob patterns of files to attach.
release-draft	false	Whether the release should be created as a draft.
release-prerelease	false	Whether the release should be marked as a prerelease.

Major-version tag alias

Input	Default	Description
major-tag	false	When true, extracts the major from the tag (e.g. v2 from v2.3.4) and force-pushes it to the current commit.

Outputs

Output	Description
version	The computed version (tag with leading v optionally stripped).
is-tag	Whether the workflow ref is a tag.
release-notes	Extracted release notes for the tag, if the changelog step ran.
release-url	URL of the created release, if any.
devbuild-url	URL of the created devbuild release, if any.

Permissions

The calling workflow needs contents: write for any step that pushes tags, commits, or creates releases. When commit-back or devbuild-tag pushing must target a protected branch, pass a PAT as committer-token.

Versioning

This action follows semver via v{major}.{minor}.{patch} tags.

Acknowledgements

This action wraps several great community actions:

• thomaseizinger/keep-a-changelog-new-release

• ffurrer2/extract-release-notes

• stefanzweifel/git-auto-commit-action

• softprops/action-gh-release