PR-based Github Action for releasing Node.js projects.
⚠️ This project is still in experimental phase, it is subject to breaking changes and therefore not suitable for production.
Issues can be tracked here, don't hesitate to upvote issues you want to be treated. If you have any question, remark, suggestion, ... They are most welcome in the discussions!
It can be quite a hassle to find a proper release process that meet simple but specific and multiple demands, such as:
- To bump automatically the version based on changes type (patch, minor, major);
- To only modify
package.json
; - To be able to ignore a specific change;
- To handle releases through a release PR;
- To create a GitHub release;
- To be able to override the version;
- To release as pre-release (both the version number and the GitHub release);
- Etc...
Some tools get close but not enough. That's exactly why Release Action exists: it is a simple automation tool for releasing Node.js projects on GitHub based on pull requests and labels. You can easily integrate it into your workflow as it only creates a GitHub release when a specific PR is merged. It works in two phases:
- Prepare: Gets all merged PRs since last release, determines the next version based
on labels (major, minor, patch) unless overriden (see inputs) and creates
(or updates) a pull request including the bumped version in
package.json
file; - Release (actually runs first): Once the release PR merged, a release is made on GitHub, that's it!
sequenceDiagram
autonumber
participant D as Developments
participant P as Production Branch
participant R as Release PR
D ->> P: Merge PR #35;1 (fix)
P -->> R: Open PR #35;2 (automatic)
Note over P,R: Release v1.0.1
D ->> P: Merge PR #35;3 (feature)
P -->> R: Update PR #35;2 (automatic)
Note over P,R: Release v1.1.0
R ->> P: Merge
Note over P: Release v1.1.0
Below is the prepare process when new changes are detected:
flowchart LR
N1{PR exists?} -- Yes --> N2{New version?}
N2 -- Yes --> C[Commit]
N2 -- No --> PR
C --> PR[PR]
N1 -- No --> N3{Branch exists?}
N3 -- Yes --> C
N3 -- No --> B[Branch]
B --> C
It should be used if:
- Commits are systematically pushed to the main/production branch through pull requests;
- Labels are used in PRs to classify the type (patch, minor, major);
- The release commit is just about updating the
package.json
file.
It should not be used if:
- Commits are pushed directly to the main/production branch;
- The release commit must include more than updating the
package.json
file, such as a changelog (the changelog is generated in the PR body and GitHub release).
Release Action is designed to be ran every time there is a change on the main/production branch. Here is a recommended workflow setting:
name: Release
on:
push:
branches:
- main
workflow_dispatch:
inputs:
release-as:
type: string
description: Force the release version
pre-release:
type: choice
default: ""
description: Pre-release
options:
- ""
- alpha
- beta
- rc
permissions:
contents: write
pull-requests: write
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
jobs:
release:
name: Release
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Execute action
id: action
uses: cyberspace7/release-action@v0.1.0
with:
release-as: ${{ inputs.release-as }}
pre-release: ${{ inputs.pre-release }}
⚠️ Use a manual version (v0.1.0
in the example) until av1
becomes available. Remember that this version is not production ready.
💡 Tip: Use the
is-released
output (see outputs) to execute another job to deploy the fresh release (i.e. create a package, deploy a Docker container, etc.).
When opening a PR on the main/production branch, use one (or more) of the following labels in order to bump the version to the right level. Labels and branches can be customised through inputs.
type: fix
: Bump the patch part of the version.type: feature
: Bump the minor part of the version.breaking
: Bump the major part of the version, or minor if current version is under1.0
.changelog-ignore
: Dont bump whatever other labels are. It should be excluded from the release notes generation (see bellow).
That's it, when merged, you should find an open release PR. You just have to merge it when you wish to release, voilà!
Changes are found comparing GitHub
generated release notes,
therefore it's advised to have a .github/release.yml
file excluding release PR labels and
the ignore label so that they don't appear as changes:
changelog:
exclude:
labels:
- "changelog-ignore"
- "release: ready"
- "release: done"
Something's missing? Check if it's planned in issues, upvote it, or share your thoughts in the discussions. Don't hesite also to share your experience.
This action requires the following permissions in order to work:
permissions:
contents: write
pull-requests: write
Name | Description | Default Value |
---|---|---|
release-as |
Force a specific version. | |
pre-release |
Name of the pre-release version (alpha , beta , rc ...). If not empty, will trigger a pre-release. |
|
label-ignore |
Label for pull requests to be ignored for the release bump. It should be added to changelog excluded labels (see #usage). | changelog-ignore |
label-patch |
Label for pull requests to bump a patch version. | type: fix |
label-minor |
Label for pull requests to bump a minor version. | type: feature |
label-major |
Label for pull requests to bump a major version. | breaking |
label-ready |
Label automatically used by Release Action for release PRs. | release: ready |
label-done |
Label automatically used by Release Action for release PRs that have been processed (current version released). | release: done |
branch-production |
Branch used for production, the base for all PRs going to production. | main |
branch-release |
Branch used for release PRs. | releases/next |
Name | Type | Description |
---|---|---|
current-version |
string |
Version of the current code. |
next-version |
string |
Version of the next release. |
release-pr |
number |
Number of the opened release pull request. |
is-released |
boolean |
Current version has been released. |
None.
Name | Description |
---|---|
GITHUB_TOKEN |
Authentification token used for GitHub API. |
See package.json
for the list of available scripts.
This project require the following dependencies:
Install the dependencies:
pnpm install
Source files are are compiled into a single file with all dependencies, into dist
.
The dist
directory must be commited into the repository.
pnpm build
Releases are automatic, following the merge of the release pull request (see Release Action). A release PR can be explicitely generated by running manually this workflow.
- Benjamin Guibert – main author and contributor.
Submit a feature request or any idea to improve the project, as it is greatly appreciated, in the discussions.
If you find a bug concerning this project, please fill a bug report.
If it concerns a security vulnerability, please email us at contact@a60.dev
.
For contributing, please check the guidelines.
This project is licensed under the MIT License.