How to setup Semantic Release with GitHub Actions.
Tags: todayilearned, cicd, githubactions, tutorial
Published: 2024-03-29 11:35:20

Recently, My coworker is using [Nx](https://nx.dev) to automate his workflow, including automated release using semantic version. I found this method quite useful, so I want to re-implement on single GitHub repositories (without Nx).

### First Step: Create GitHub's Personal Access Token
You can follow this [link](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) on how to create Personal Access Token.
You can choose **Fine-grained tokens** as you can scope specific repositories. (Or **Token (Classic)**)

![menu](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wei6d4lsfhnhqd5pn8cp.png)

Make sure that you grant repository permission to token. For my configuration I use:

**Read Access**
- variables
- environments 
- metadata (default)
- secrets

**Read/Write Access**
- code
- commit statuses
- issue
- pull requests
- workflows

> _I might grant unnecessary permission, so feel free to correct me._

### Second Step: Setup GitHub token in repository's environment

1.Go to `Settings` options
![setting](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/weev9ivc5els621ewlsa.png)

2.Select `Environments`

![select environment](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/p1g8n3grrks7l4fwl0gr.png)

3.Create Environment

![create environment](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fz19mhnfbj2wgwhunkr1.png)

4.Create Environment Secret

![environment secret](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b3ph1ynjx9cv4i7b2tj9.png)

> I use `GH_TOKEN` to represent `GITHUB_TOKEN` (GitHub does not allow naming variables with prefix "GITHUB").

### Third Step: Setup workflows
I use this package -> [Action for Semantic Release](https://github.com/marketplace/actions/action-for-semantic-release) to setup my workflow.
Use this script to create workflow
```yaml
name: test
on:
  push:
    branches:
      # Change this if your primary branch is not main
      - master
      - dev

jobs:
  main:
    runs-on: ubuntu-latest
    environment:
      name: Semver #your environment name
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Semantic Release
        uses: cycjimmy/semantic-release-action@v4
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
```
In this code snippets, it's meant to
- setup environment
- perform semantic release

### Fourth Step: Create `.releaserc`
This will be `semantic-release` configuration file for
- create release tag
- create change log
- define commit message convention -> [conventionalcommits](https://www.conventionalcommits.org/en/v1.0.0/)

Create `.releaserc` in your project.
```yaml
{
    "branches": [
        "master",
        "dev"
    ],
    "plugins": [
        "@semantic-release/commit-analyzer",
        "@semantic-release/release-notes-generator",
        [
            "@semantic-release/changelog",
            {
                "changelogFile": "CHANGELOG.md"
            }
        ],
        [
            "@semantic-release/git",
            {
                "assets": [
                    "CHANGELOG.md"
                ]
            }
        ],
        "@semantic-release/github"
        
    ]
}
```

### Final Step: Add, Commit and Push
This step will be the byproduct of your work so far.

Once you commit your code with message convention, for example, `feat: add some features`, it will trigger the `semantic-release`. Default convention message with `angular` preset included:
- `fix` -> bug fixes: patch release
- `feat` -> feature: minor release
- `breaking change` -> break change: major release

Once you push your code it will run GitHub Action and release your project.

![github action](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wxfkd132m4yuw0d54ksw.png)

Then it will create `Release` and `CHANGELOG.md` in the project.

![release](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nylw1djioyiaobnq6nfy.png)

![changelog](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8otoh032qe52w2na20xo.png)

### Conclusion
`semantic-release` can help you automate your versioning and release. Also, It's really useful for tracking and change in document.

Feel free to comment or give feedbacks. I'm appreciate your time for reading 😄.

### Reference
https://www.conventionalcommits.org/en/v1.0.0/
https://github.com/marketplace/actions/action-for-semantic-release

Or my sample repository -> https://github.com/Sahanon-P/semver-sample