git-release

A GitHub Action for a GitHub Release creation with Assets and Changelog on new Git Tag in the repository.

Features

• Parse Tag to match Semantic Versioning
• Upload build artifacts (assets) to the release
• Publish release with changelog
  • Keep a Changelog Compliant
  • Common Changelog Compliant
• Customizable release name and body through Go templates
• Supported runners:
  • Linux AMD64
  • Linux ARM64
  • Windows
• Filename pattern matching
• Supports GitHub Enterprise
• Supports standard v prefix out of the box
• Allows custom SemVer prefixes
• Update a single pre-release with changes from Unreleased scope
• Retry assets upload on network interrupts

Manual

1. Add changes to CHANGELOG.md. For example:

   ## [3.4.0] - 2020-07-10
   ### Added
   - Glob pattern support
   - Unit Tests
   - Log version
   
   ### Fixed
   - Exception on margins larger than context of changelog
   - Nil pointer exception in 'release' package
   
   ### Changed
   - Refactor JavaScript wrapper
   
   ## [3.3.0] - 2020-06-27
   ### Added
   - Wrapper script: allow execution on Windows runners
   
   ### Changed
   - Action execution through Git: from Docker to NodeJS
   
   [3.4.0]: https://github.com/anton-yurchenko/git-release/compare/v3.3.0...v3.4.0
   [3.3.0]: https://github.com/anton-yurchenko/git-release/releases/tag/v3.3.0

2. Tag a commit with Version (according to semver.org)

3. Push and watch Git-Release publishing a Release on GitHub 😉

   

Configuration

1. Change the workflow to be triggered on new Tag:

   • For example '*' or a more specific like 'v*':

   on:
     push:
       tags:
       - "v[0-9]+.[0-9]+.[0-9]+"

2. Add Release step to your workflow:

       - name: Release
         uses: docker://antonyurchenko/git-release:v7
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           args: build/*.zip

3. Configure Release step:

   • Specify release assets as action arguments (divided by one of: new line, space, comma, pipe)
   • Fine tune action configuration using environmental variables:

   Environmental Variable	Allowed Values	Default Value	Description
   DRAFT_RELEASE	true/false	false	Publish a draft release
   PRE_RELEASE	true/false	false	Mark release non-production ready
   CHANGELOG_FILE	*	CHANGELOG.md	Changelog filename (set none to silence a warning message if file does not exist)
   ALLOW_EMPTY_CHANGELOG	true/false	false	Allow publishing a release without changelog
   TAG_PREFIX_REGEX	*	v?	Version tag prefix regex, for example [a-z-]* in order to parse prerelease-1.1.0
   NAME_TEMPLATE	*	""	Release title as a template. Default: the tag
   BODY_TEMPLATE	*	""	Release body as a template. Default: the changelog
   UNRELEASED	update/delete	""	Set to update in order to allow deletion and recreation of the same release and its tag (intended to be used for unreleased/latest release only). Set to delete in order to delete a previously published unreleased/latest release.
   UNRELEASED_TAG	*	latest	Use a custom tag for unreleased/latest release (tag will be created/deleted automatically)

   Configuration is provided as environmental variables (strings), so do not forget to enclose boolean values with quotes

   ⚠️ Upgrading from v6

   v6	v7
   RELEASE_NAME: "Ship It"	NAME_TEMPLATE: "Ship It"
   RELEASE_NAME_PREFIX: "Release: "	NAME_TEMPLATE: "Release: {{ .Tag }}"
   RELEASE_NAME_SUFFIX: " (nightly)"	NAME_TEMPLATE: "{{ .Tag }} (nightly)"
   both prefix and suffix	NAME_TEMPLATE: "Release: {{ .Tag }} (nightly)"
   DRAFT_RELEASE: "yes" was silently false	any value other than true/false is now an error

   Removed variables fail the run with a message naming their replacement, rather than being ignored. Everything else is unchanged.

ℹ️ Release Name and Body Templates

By default the release title is the tag and the body is the changelog section of the released version. NAME_TEMPLATE and BODY_TEMPLATE replace them with Go templates rendered with the following fields:

Field	Description
.Tag	Git tag, for example v1.2.3
.Version	Semantic version, for example 1.2.3 (or Unreleased)
.Major .Minor .Patch	Semantic version components
.Prerelease	Semantic version pre-release identifier, for example rc.1
.Owner	Repository owner
.Repo	Repository name
.CommitHash	Commit the release points to
.IsDraft	true when the release is a draft
.IsPreRelease	true when the release is a pre-release
.IsUnreleased	true for a rolling unreleased release
.Changelog	Changelog entries of the released version. BODY_TEMPLATE only
.Name	The rendered release title. BODY_TEMPLATE only

The name is rendered before the changelog is read, so .Changelog and .Name are available to the body template only.

A reference to a field that does not exist terminates the action instead of silently rendering an empty value.

ℹ️ {{ ... }} here is a Go template, not a GitHub Actions ${{ ... }} expression - GitHub does not interpolate it.

name: release

on:
  push:
    tags:
      - "*"

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Release
        uses: docker://antonyurchenko/git-release:v7
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NAME_TEMPLATE: "Release {{ .Tag }}{{ if .IsPreRelease }} (pre-release){{ end }}"
          BODY_TEMPLATE: |
            ## {{ .Name }}

            {{ .Changelog }}

            ---
            Released from `{{ .CommitHash }}` in `{{ .Owner }}/{{ .Repo }}`
        with:
          args: build/*.zip

ℹ️ Windows Runners

Execute git-release through JavaScrip Wrapper on Windows Runners.

    - name: Release
      uses: anton-yurchenko/git-release@v7
      with:
        args: |
            build\\darwin-amd64.zip
            build\\linux-amd64.zip
            build\\windows-amd64.zip

ℹ️ Configuration Examples

Remarks

• This action has multiple tags: latest / v1 / v1.2 / v1.2.3. You may lock to a certain version instead of using latest.
  (Recommended to lock against a major version, for example v7)
• Instead of using a pre-built Docker image, you may execute the action through JavaScript wrapper by changing docker://antonyurchenko/git-release:v7 to anton-yurchenko/git-release@v7
• git-release operates assets with pattern matching, this means that it is unable to validate whether an asset exists
• Docker image is published both to Docker Hub and GitHub Packages. If you don't want to rely on Docker Hub but still want to use the dockerized action, you may switch from uses: docker://antonyurchenko/git-release:latest to uses: docker://ghcr.io/anton-yurchenko/git-release:latest
• git-release may crash when executed against a not supported changelog file format. Make sure your changelog file is compliant to one of the supported formats.

License

MIT © 2019-present Anton Yurchenko