https://github.com/mgoltzsche/conventional-release
A GitHub Action to automate releases based on Conventional Commits
https://github.com/mgoltzsche/conventional-release
conventional-changelog conventional-commits release release-automation release-notes semantic semantic-version semantic-versioning version
Last synced: 4 months ago
JSON representation
A GitHub Action to automate releases based on Conventional Commits
- Host: GitHub
- URL: https://github.com/mgoltzsche/conventional-release
- Owner: mgoltzsche
- License: apache-2.0
- Created: 2023-07-14T23:57:53.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-14T20:57:36.000Z (almost 2 years ago)
- Last Synced: 2025-02-15T17:39:40.641Z (about 1 year ago)
- Topics: conventional-changelog, conventional-commits, release, release-automation, release-notes, semantic, semantic-version, semantic-versioning, version
- Language: Shell
- Homepage:
- Size: 48.8 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# conventional-release 
A GitHub Action to automate releases based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) using [sv4git](https://github.com/bvieira/sv4git).
## Features
* Supports fully automated releases driven by Conventional Commits.
* Allows to disable automated versioning in favour of manually pushing tags (`auto-release: false`).
* Enforces [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format within commit messages.
* Recovers from a failed release build automatically (when the next commit is pushed).
* Allows to use the same workflow/job definition for both pull request and release builds.
* Fails builds that leave uncommitted changes.
## Usage
To enable automated releases within your workflow, add a step to runs this Action after `actions/checkout` and before your actual build step(s):
```
- id: release
name: Prepare release
uses: mgoltzsche/conventional-release@v0
```
For all supported Action inputs and outputs, see [`./action.yml`](./action.yml).
Please note that the releasing job needs to have write permissions for `contents` in order to push a git tag and create a GitHub release.
In case of pull request builds, the token still provides read-only access this way.
Correspondingly the `actions/checkout` Action should be configured with `persist-credentials: false`.
Please also note that the `actions/checkout` Action must be configured with `fetch-depth: 0` to work with the release Action.
To run subsequent steps conditionally depending on whether it is a release build, use the Action output `publish` as condition.
(In case of a release build, a git tag is pushed and a GitHub release created by the Action's post-entrypoint only after all steps within the job succeeded.)
Corresponding to its outputs, the Action exports the following environment variables to subsequent steps:
* `RELEASE_VERSION`: The semantic version (or manually pushed tag) of the release without leading `v`. During non-release builds this holds the next version with a `-dev-` suffix.
* `RELEASE_PUBLISH`: Is `true` when release build, otherwise empty.
### Example workflow
A workflow that creates releases based on commits on the main branch automatically and that validates pull requests can look as follows:
```yaml
name: Build and release
on:
push:
branches:
- main
pull_request:
branches:
- main
concurrency: # Run release builds sequentially, cancel outdated PR builds
group: ci-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
permissions: # Grant write access to github.token within non-pull_request builds
contents: write
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v3
with:
fetch-depth: 0
persist-credentials: false
- id: release
name: Prepare release
uses: mgoltzsche/conventional-release@v0
# ... Build artifact ...
- name: Publish artifact
if: steps.release.outputs.publish # To run only when release build
run: |
set -u
echo Publishing $RELEASE_VERSION
...
```
The [workflow used to publish this Action](./.github/workflows/workflow.yaml) is another example that shows how to release a container image, add a release commit and force-push a major version tag.
## Design considerations
See [design considerations](./DESIGN.md).