Previously I talked about semantic version and why it is important to follow the guidelines for versioning, in this part of the series i will talk about how to maintain the package versioning automatically using semantic release package.
Here is a short description about semantic release from the authors:
semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.
Semantic release is relying on the commit format to determine the next release based on it. You can configure any format you want, the default format is angular message format. for example if we have a package version 1.0.0
, a commit message with this format:
-
feat: added new feature
will bump the version to 1.1.0 -
fix: added more config
will bump the version to 1.0.1
For more details about how semantic release works you can find it here.
Note: If you didn't follow the naming conventions, semantic release package won't be able to determine the next release version. Also it would be a problem when you have a large team and you want all of them to follow the rules, luckily there are packages for this, we will talk about them shortly.
I will use semantic release in a simple react project and will use Github actions along with Github packages to automate our workflow.
You can find a full example that we want to achieve at the end of this series here. Get Ready ๐ฅ
Table Of Contents
- Prerequisites ๐
- Installing semantic release package ๐ฆ
- Configure Semantic Release package โ๏ธ
- Pipeline Setup โถ๏ธ
- See the workflow in action ๐งช
Prerequisites ๐
- Basic knowledge of CI/CD workflow, you can refer to my 2 mins article about this topic.
- Installed npm >=5.2.0
- Installed Git.
- Fresh repository hosted on Github.
- Create Github token, this will be used by semantic release package.
Installing semantic release package ๐ฆ
We will use sematnic release CLI package for quick installation. This will help us to configure multiple things:
- Git repository.
- Package Manager repository (Github packages)
- Continuous Integration platform (Github actions) Use this command to configure our workflow:
npx semantic-release-cli setup
You will be asked several questions about your credentials and configuration
-
NPM registry the registry which you will store your package on it, in our case this we will use Github packages, so copy this url
https://npm.pkg.github.com/
and press enter. - Authentication Method Choose token based authentication.
- NPM username here we will configure our Github packages credentials, so you need to enter your github username.
- NPM password this will be the github token which you have generated it earlier.
- Github username this will be the same as username you enterd in NPM username, so enter it again ๐ .
- Github password wrtie your Github password.
- Which CI we will be using Github actions, so choose the last option (other).
If everything goes Ok, the CLI will print out GH_TOKEN
and NPM_TOKEN
. These values will be used by our CI (Github actions), to be able to push automated commits and publish your package to Github packages.
Now we are going to use GH_TOKEN
and NPM_TOKEN
and we will create new secrets in Github, which will be used by our pipelines.Go to your repository settings -> find secrets tab in the left panel -> create two secrets, one for GH_TOKEN
and the other forNPM_TOKEN
. See below image:
Edit your package.json
file and add our publish config:
"publishConfig": {
"registry": "https://npm.pkg.github.com/",
"pkgRoot": "build"
}
pkgRoot
key is a path to your build directory, here we are using create-react-app
to build our package and produce the result to build directory. With these configations we will able to publish our package to Github packages.
Also change the version value of your package.json
file and let it start with 1.0.0
"version":"1.0.0"
Configure Semantic Release package โ๏ธ
Semantic Release has several configuration out of the box, we will use some of them to build our workflow:
- Create a new file (
.releaserc.json
) in your root directory (there are other ways to create this file. - copy the content of this gist to your
.releaserc.json
file and changerepositoryUrl
to your repository url.
You may want to follow the documentation for more clarification.
The default plugins used be semantic release package are ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']
I added two more external plugins @semantic-release/changelog (to create an automated changelog file) and @semantic-release/git (to bump version in package.json and package-lock.json files and create a new commit with this change)
Dont forget to install them in your dev dependencies
npm install @semantic-release/git -D && npm install @semantic-release/changelog -D
Pipeline Setup โถ๏ธ
To Define your Github actions, create .github
folder in your root project path and add workflows
folder inside it. After that create your action, for example : ci.yml
. A full path should be like this .github/workflows/ci.yml
.
Here is a full example of basic CI using semantic release command, copy this example to your action file and replace SEMANTIC_RELEASE_GH_TOKEN
and SEMANTIC_RELEASE_NPM_TOKEN
with your secrets name.
You may noticed that we add this condition the build process if: "!contains(github.event.head_commit.message, 'skip ci')"
, this means that any commit message contains skip ci will not trigger complete the process of the pipelines, this is useful you wish to pervert unnecessary pipelines triggers for some commit messages.
See the workflow in action ๐งช
Now push your commits to your repository and navigate to actions tab in your repository and watch your pipelines progress. If everything goes well you should see a green indicators in all of action's steps.
Semantic release package has created a new release, you can view it in releases tab. Also you can view your deployed package at packages tab
Configurations๐ now you have a built a basic automated workflow with github actions and semantic release package. Next we will continue our setup and implement the continues deployment part to deploy our app to Github pages.
Thanks to freepik platform, i was able to build my article covered using their awesome designs.
Business vector created by macrovector - www.freepik.com
Top comments (0)