? 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 reuse 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: softprops/action-gh-release@v1
if: startsWith(github.ref, 'refs/tags/')
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
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: softprops/action-gh-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
⬆️ Uploading release assets
You 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: softprops/action-gh-release@v1
if: startsWith(github.ref, 'refs/tags/')
with:
files: Release.txt
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
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: softprops/action-gh-release@v1
if: startsWith(github.ref, 'refs/tags/')
with:
files:, Release.txt
LICENSE
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
⚠️ 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: softprops/action-gh-release@v1
if: startsWith(github.ref, 'refs/tags/')
with:
body_path: ${{ github.workflow }}-CHANGELOG.txt
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
? Customizing
inputs
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 this release is a 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, tag_name, String, Name of a tag. defaults to github.ref, ?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.
outputs
The following outputs can be accessed via ${{ steps.<step-id>.outputs }} from this action, Name, Type, Description, -------------, ---------, -----------------------------------------------------------------, url, String, Github.com URL for the release, #### environment variables
The following are required as step.env keys, Name, Description, ----------------, --------------------------------------, GITHUB_TOKEN, GITHUB_TOKEN as provided by secrets, > ⚠️ Note: This action was previously implemented as a Docker container, limiting its use to GitHub Actions Linux virtual environments only. With recent releases, we now support cross platform usage. You'll need to remove the docker:// prefix in these versions
Doug Tangren (softprops) 2019