action gh-release

A GitHub Action for creating GitHub Releases on Linux, Windows, and OSX virtual environments

⚠️ Note: To use this action, you must have access to the GitHub Actions feature. GitHub Actions are currently only available in public beta. You can apply for the GitHub Actions beta here.

Table of Contents

Details

• 🤸 Usage
  • 🚥 Limit releases to pushes to tags
  • ⬆️ Uploading release assets
  • 📝 External release notes
  • 💅 Customizing

🤸 Usage

🚥 Limit releases to pushes to tags

Typically usage of this action involves adding a step to a build that is gated pushes to git tags. You may find step.if field helpful in accomplishing this as it maximizes the resuse value of your workflow for non-tag pushes.

Below is a simple example of step.if tag gating

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Release
        uses: technote-space/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')

You can also use push config tag filter

name: Main

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Release
        uses: technote-space/action-gh-release@v2

⬆️ Uploading release assets

You can can configure a number of options for your GitHub release and all are optional.

A common case for GitHub releases is to upload your binary after its been validated and packaged. Use the with.files input to declare a newline-delimited list of glob expressions matching the files you wish to upload to GitHub releases. If you'd like you can just list the files by name directly.

Below is an example of uploading a single asset named Release.txt

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Build
        run: echo ${{ github.sha }} > Release.txt
      - name: Test
        run: cat Release.txt
      - name: Release
        uses: technote-space/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: Release.txt

Below is an example of uploading more than one asset with a GitHub release

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Build
        run: echo ${{ github.sha }} > Release.txt
      - name: Test
        run: cat Release.txt
      - name: Release
        uses: technote-space/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: |
            Release.txt
            LICENSE

⚠️ Note: Notice the | in the yaml syntax above ☝️. That let's you effectively declare a multi-line yaml string. You can learn more about multi-line yaml syntax here

📝 External release notes

Many systems exist that can help generate release notes for you. This action supports loading release notes from a path in your repository's build to allow for the flexibility of using any changelog generator for your releases, including a human 👩‍💻

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Generate Changelog
        run: echo "# Good things have arrived" > ${{ github.workflow }}-CHANGELOG.txt
      - name: Release
        uses: technote-space/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')
        with:
          body_path: ${{ github.workflow }}-CHANGELOG.txt

💅 Customizing

inputs

The following are required as step.with keys

Name	Description
GITHUB_TOKEN	GITHUB_TOKEN as provided by secrets

The following are optional as step.with keys

Name	Type	Description
body	String	Text communicating notable changes in this release
body_path	String	Path to load text communicating notable changes in this release
draft	Boolean	Indicator of whether or not to create release as draft
update_draft_flag	Boolean	Indicator of whether or not to update draft
update_draft_mode	Boolean	Indicator of whether or not to update release as draft
prerelease	Boolean	Indicator of whether or not is a prerelease
files	String	Newline-delimited globs of paths to assets to upload for release
name	String	Name of the release. defaults to tag name

💡When providing a body and body_path at the same time, body_path will be attempted first, then falling back on body if the path can not be read from.

Doug Tangren (softprops) 2019
Technote 2019