Conventional Commit Release Notes Generator for GitHub
Use the Conventional Commits standard to auto-generate release notes.
This tool is designed to be consumed as a Docker image and called as part of your CI pipeline. It is optimised to run following an application promotion workflow. This project uses itself to generate it's own changelogs using Google Cloud Build, so examine the cloudbuild.latest.yaml file for reference on how to consume it.
The utility can simply be added to your existing build workflow by consuming it as a Docker container. Simply mount
your source code to a
/workspace volume and start the container. The changelog will be output. If you use Google Cloud
Build, then this mount is done automatically.
This command will run the container on the current git directory and output the changelog.
docker run --rm -it -v $(pwd):/workspace gcr.io/conventional-github-releaser/conventional-github-releaser
To enable automatic publishing to Github Releases, you need to configure the following environment variables.
GITHUB_API_TOKEN- A personal access token with 'repo' permissions.
GITHUB_REPO- The name of the repository that will have the changelog written to.
GITHUB_OWNER- The name of the repository owner. This is the organisation name or personal username on Github.
To enable automatic examination and upload of Webpack bundle stats file and reports, set the following environment variable.
APP_VERSIONThe short git has of the commit that is being promoted. Usually the current git short SHA. For example, if you set the value to
015e3d2, then this tool will look for
015e3d2-bundle-report.htmlin the current working directory, if none is found, it will also look in a
./reports/directory if it exists. You should ensure that the relevant file is unarchived by your build system in advance of running this tool.
If you want to run the changelog for a tag that is not the latest, then set the following variable:
APP_TAG, set this to the git tag that should be reported. When omitted, by default a change log will be generated from the latest git tag and the one previous to it. Tags must be semver based. If you want to generate an older report, set the
APP_TAGto the tag. If the tag is not found, it is ignored and revert to default behaviour.
You can also create draft releases, by including
--draft in the command line as a argument. This will generate a report
from the current commit from the last previous tag. No upload or release publish will take place. If an
APP_TAG is specified,
--draft flag is ignored.
If you commit direct to the working branch, then this tool will analyse conventional commit formatted commits to produce the
report. Say however, you run a full Pull Request workflow, then you will have only merge and squash commits that cannot be analysed.
This means the report will have no data, so you should include the
--pull-request-based command line argument telling
the tool to include merge commits.
You can also prevent the upload of GitHub Release Notes by including the
--no-upload arguments. The
will upload the report, but not upload the relevant Webpack bundle results.
docker run --rm -it -v $(pwd):/workspace gcr.io/conventional-github-releaser/conventional-github-releaser --pull-request-based
Building and Commands
The script is added to a Docker image without any compile steps.
yarn startto run the script on the current repo, great for testing.
yarn build:dockerto generate the Docker image.
This tool is based upon the Conventional Changelog Github Releaser which is a prebuilt tool for grabbing commits and publishing a release notes on GitHub, I wanted to extend the formatting and the grabbing of different tag types in projects that do not adhere to SemVer (for example in website projects where semver makes little practical sense).
The spec for commits outlines the format of each specific commit, while the changelog spec outlines how these commits are grouped, formatted, and placed under semver control. Two different specs, but easy to get mixed up.
How this tool differs
- Applies custom formatting over the existing preset.
- Is triggered after tagging with no additional commits. This enables full image promotion rather than making a release commit and rebuilding. Thus this tool does not generate tags, suggestion version numbers, or make git commits.
- It uses the latest generation ECMAScript.
- Examines and uploads Webpack Bundle files for statistical analysis.
- Consumed via Docker