Showcases how to automate release processes using GitHub Actions.
It is designed for a specific release methodology, but can be adapted for other approaches. Key features include:
- Semantic versioning with a preceding
v
in tags and releases (e.g.,v1.0.3
). - Releases are triggered upon tag push.
- Release notes are automatically extracted from the CHANGELOG.md file.
- Release titles are generated from a pattern recognized by a script in the workflow file, starting with
#
followed by the space and version tag.
We primarily utilize softprops/action-gh-release for its simplicity and versatility.
However, for those looking for alternatives, especially since actions/create-release is no longer maintained, consider:
By default, workflow uses GITHUB_TOKEN with default restricted
permissions, which is not enough to do a release. There are several options to deal with it:
-
Adjust GITHUB_TOKEN Permissions: Navigate to
Settings > Actions > General
in your repository, findWorkflow permissions
, and selectRead and write permissions
. -
Specify more granular permissions: Within your workflow's YAML file, specify necessary permissions as follows:
permissions: actions: write contents: write
Contents
write
permission in required to create a release. Actionswrite
permissions in is required to callworkflow_dispatch
event. -
Use a Personal Access Token (PAT): Create a PAT under
Settings > Developer Settings > Personal access tokens > Generate new token
withAll repositories
access and writeActions
(if you use dispatch event) andContents
permissions. Add this token to your repository's secrets (Settings > Secrets and variables > Actions > New repository secret
) and reference it asWORKFLOW_TOKEN
in your workflows.
| Note: Using actions/download-artifact
to read an artifact from one workflow to another requires PAT with Actions read
permissions.
Once the changelog file is parsed, the notes will be passed between steps, so they need to be stored somewhere. The problem occurs when a release note contains multiple lines. To avoid problems with multi-line data, you should either remove special characters or use Here Document.
-
Escaping. It is common practice to replace
%
,\n
,\r
with their URL-encoded equivalents.CHANGELOG_CONTENT="${CHANGELOG_CONTENT//'%'/'%25'}" CHANGELOG_CONTENT="${CHANGELOG_CONTENT//$'\n'/'%0A'}" CHANGELOG_CONTENT="${CHANGELOG_CONTENT//$'\r'/'%0D'}"
| Note: Using this string in the body of the release will likely cause the notes to be displayed as is, without being decoded.
-
HereDoc. Not a true Here Document per se, rather simulates the effect of appending a HereDoc-like structure to the output output. Notes can later be accessed via
${{steps.<step_id>.outputs.<variable_name>}}
.echo "changelog_content<<EOF" >> $GITHUB_OUTPUT echo "$CHANGELOG_CONTENT" >> $GITHUB_OUTPUT echo "EOF" >> $GITHUB_OUTPUT
Content can also be written to
$GITHUB_ENV
and later accessed via${{env.CHANGELOG_CONTENT}}
.
There are several common approaches to using the release workflow. Typically, you want to test your code before releasing it. So it makes sense to do a release after the application has been built and tested.
The simplest way is to use a single file for all work. This approach may be suitable for small projects with simple workflows.
Associated files:
This approach is suitable for cases where you want to have a separate workflow for release, for example your workflow files are large and you have many of them.
| Note: In addition to the above, you can run this "Release from Dispatch" release workflow on the Actions tab of the repository by specifying a tag
value.
| Note: This event will only trigger the workflow if the workflow file is in the default branch.
Associated files:
Suitable for large projects, with multiple workflows and artifacts passed between them.
More than one type of activity triggers this event. But we are only interested in the completed
activity.
| Note: This event will only trigger a workflow if the workflow file is in the default branch.
Associated files: