Shareable semantic-release configuration

A shareable semantic-release configuration, for enforcing consistent GitHub/NPM releases in your projects.

^{Daniel Bannert's open source work is supported by the community on GitHub Sponsors}

Purpose

This configuration also includes a semantic-release configuration, which enables automated GitHub/NPM releases based on your commit messages.

Install

npm install --dev-save semantic-release @anolilab/semantic-release-preset

yarn add -D semantic-release @anolilab/semantic-release-preset

pnpm add -D semantic-release @anolilab/semantic-release-preset

Plugins

We use the following plugins within the Semantic Release ecosystem:

@semantic-release/changelog
@semantic-release/commit-analyzer
@semantic-release/exec
@semantic-release/git
@semantic-release/github
@semantic-release/npm (optional)
@semantic-release/release-notes-generator
@anolilab/semantic-release-pnpm (optional)
semantic-release-yarn (optional)

Summary

This shareable configuration performs the following actions:

Analyze commits (@semantic-release/commit-analyzer)
Generate changelog content (@semantic-release/release-notes-generator)
Create or update a changelog file generated by step 2 (@semantic-release/changelog)
Update the package version to the next release version
Commit release assets to the project’s git repository with the commit message chore(release): ${nextRelease.version} [skip ci] ${nextRelease.notes}.
Publish a npm release with (@semantic-release/npm or @anolilab/semantic-release-pnpm or semantic-release-yarn) (optional)
Publish a GitHub release and comment on released Pull Requests/Issues (@semantic-release/github)

Usage

When installing this package for the first time, the following shareable configuration .releaserc.json is automatically added to your project folder:

Note: If the script detects an existing .releaserc.json file, it will not overwrite it.

Note: It can happen that the postinstall script don't run, then you have to add the .releaserc.json manually.

Npm release with @semantic-release/npm:

{
    "extends": "@anolilab/semantic-release-preset/npm"
}

Npm release with @anolilab/semantic-release-pnpm:

{
    "extends": "@anolilab/semantic-release-preset/pnpm"
}

Npm release with semantic-release-yarn:

{
    "extends": "@anolilab/semantic-release-preset/yarn"
}

Without npm release:

{
    "extends": "@anolilab/semantic-release-preset"
}

File content of the extended preset

{
    branches: [
        "+([0-9])?(.{+([0-9]),x}).x",
        "main",
        "next",
        "next-major",
        {
            name: "beta",
            prerelease: true,
        },
        {
            name: "alpha",
            prerelease: true,
        },
    ],
    plugins: [
        [
            "@semantic-release/commit-analyzer",
            {
                preset: "conventionalcommits",
            },
        ],
        [
            "@semantic-release/release-notes-generator",
            {
                preset: "conventionalcommits",
            },
        ],
        "@semantic-release/changelog",
        "@semantic-release/npm", // optional
        [
            "@semantic-release/git",
            {
                message: "chore(release): ${nextRelease.gitTag} [skip ci]\\n\\n${nextRelease.notes}",
            },
        ],
        [
            "@semantic-release/github",
            {
                successComment: false,
                failComment: false,
            },
        ],
    ],
}

deprecation

You want to deprecate old versions of your package?

Option one is the semantic-release-npm-deprecate-old-versions

Install

npm install --dev-save semantic-release-npm-deprecate-old-versions

pnpm add -D semantic-release-npm-deprecate-old-versions

yarn add -D semantic-release-npm-deprecate-old-versions

No problem, just add the following to your .releaserc.json:

{
    "extends": "@anolilab/semantic-release-preset/npm",
    "plugins": [
        [
            "semantic-release-npm-deprecate-old-versions",
            {
                "rules": [
                    {
                        "rule": "supportLatest",
                        "options": {
                            "numberOfMajorReleases": 1,
                            "numberOfMinorReleases": 1,
                            "numberOfPatchReleases": 1
                        }
                    },
                    {
                        "rule": "supportPreReleaseIfNotReleased",
                        "options": {
                            "numberOfPreReleases": 1
                        }
                    },
                    "deprecateAll"
                ]
            }
        ]
    ]
}

Find out how to configure the plugin here.

Option one is the semantic-release-npm-deprecate

Install

npm install --dev-save semantic-release-npm-deprecate-old-versions

pnpm add -D semantic-release-npm-deprecate-old-versions

yarn add -D semantic-release-npm-deprecate-old-versions

No problem, just add the following to your .releaserc.json:

{
    "extends": "@anolilab/semantic-release-preset/npm",
    "plugins": [
        [
            "semantic-release-npm-deprecate",
            {
                "deprecations": [
                    {
                        "version": "< ${nextRelease.version.split('.')[0]}",
                        "message": "Please use ^${nextRelease.version.split('.')[0]}.0.0."
                    }
                ]
            }
        ]
    ]
}

Find out how to configure the plugin here.

Environment Variables Configuration

Ensure that your CI configuration has the following environment variables set:

GITHUB_TOKEN: A GitHub personal access token
- When a new release is published, this plugin will try to commit and push into the released branch. Ensure that the user that is running the release has push rights and can bypass branch protection rules.
NPM_TOKEN: A npm personal access token
- A NPM token so the package can be published to NPM (a .npmrc file with extra configuration can also be used)

You can test your config with a dry run:

npx semantic-release --dry-run

GitHub workflows

If you're configuring a GitHub workflow you might want to do a test build matrix first and then publish only if those tests succeed across all environments. The following will do just that, immediately after something is merged into main.

Here’s an example workflow configuration that runs your tests and publishes a new version for new commits on main branch:

Single semantic-release example with yarn, (you can do the same with pnpm or npm)

# https://help.github.com/en/categories/automating-your-workflow-with-github-actions

name: "Semantic Release"

on: # yamllint disable-line rule:truthy
    push:
        branches:
            - "([0-9])?(.{+([0-9]),x}).x"
            - "main"
            - "next"
            - "next-major"
            - "alpha"
            - "beta"

jobs:
    test:
        name: "Semantic Release"

        runs-on: "ubuntu-latest"

        steps:
            - uses: "actions/checkout@v2"
              with:
                  fetch-depth: 0
                  persist-credentials: false
              env:
                  GIT_COMMITTER_NAME: "GitHub Actions Shell"
                  GIT_AUTHOR_NAME: "GitHub Actions Shell"
                  EMAIL: "github-actions[bot]@users.noreply.github.com"

            - name: "Use Node.js 12.x"
              uses: "actions/setup-node@v2"
              with:
                  node-version: "12.x"

            - name: "Get yarn cache directory path"
              id: "yarn-cache-dir-path"
              run: 'echo "::set-output name=dir::$(yarn config get cacheFolder)"'

            - uses: "actions/cache@v2"
              id: "yarn-cache" # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
              with:
                  path: "${{ steps.yarn-cache-dir-path.outputs.dir }}"
                  key: "${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}"
                  restore-keys: |
                      ${{ runner.os }}-yarn-

            - name: "install"
              run: "yarn install --immutable"

            - name: "Build packages"
              run: "yarn build"

            - name: "test"
              run: "yarn run test"

    semantic-release:
        name: "Semantic Release"

        runs-on: "ubuntu-latest"

        needs: ["test"]

        steps:
            - uses: "actions/checkout@v2"
              with:
                  fetch-depth: 0
                  persist-credentials: false
              env:
                  GIT_COMMITTER_NAME: "GitHub Actions Shell"
                  GIT_AUTHOR_NAME: "GitHub Actions Shell"
                  EMAIL: "github-actions[bot]@users.noreply.github.com"

            - name: "Use Node.js 12.x"
              uses: "actions/setup-node@v2"
              with:
                  node-version: "12.x"

            - name: "Get yarn cache directory path"
              id: "yarn-cache-dir-path"
              run: 'echo "::set-output name=dir::$(yarn config get cacheFolder)"'

            - uses: "actions/cache@v2"
              id: "yarn-cache" # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
              with:
                  path: "${{ steps.yarn-cache-dir-path.outputs.dir }}"
                  key: "${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}"
                  restore-keys: |
                      ${{ runner.os }}-yarn-

            - name: "install"
              run: "yarn install --immutable"

            - name: "Build packages"
              if: "success()"
              run: "yarn build"

            - name: "Semantic Release"
              if: "success()"
              env:
                  GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
                  NPM_TOKEN: "${{ secrets.NPM_AUTH_TOKEN }}"
                  GIT_AUTHOR_NAME: "github-actions-shell"
                  GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
                  GIT_COMMITTER_NAME: "github-actions-shell"
                  GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
              run: "npx semantic-release"

To release multi package repositories, you need to install @anolilab/multi-semantic-release and semantic-release.

Multi package semantic-release example with pnpm

# https://help.github.com/en/categories/automating-your-workflow-with-github-actions

name: "Semantic Release"

on: # yamllint disable-line rule:truthy
    push:
        branches:
            - "([0-9])?(.{+([0-9]),x}).x"
            - "main"
            - "next"
            - "next-major"
            - "alpha"
            - "beta"

# Enable this to use the github packages
# yamllint disable-line rule:comments
#env:
#    package: "@${{ github.repository }}"
#    registry_url: "https://npm.pkg.github.com"
#    scope: "${{ github.repository_owner }}"

jobs:
    test:
        strategy:
            matrix:
                os: ["ubuntu-latest"]
                node_version: ["16", "18", "19", "20"]
            fail-fast: false

        name: "Build & Unit Test: node-${{ matrix.node_version }}, ${{ matrix.os }}"

        runs-on: "${{ matrix.os }}"

        steps:
            - name: "Git checkout"
              uses: "actions/checkout@v3"
              env:
                  GIT_COMMITTER_NAME: "GitHub Actions Shell"
                  GIT_AUTHOR_NAME: "GitHub Actions Shell"
                  EMAIL: "github-actions[bot]@users.noreply.github.com"

            - uses: "pnpm/action-setup@v2.2.4"
              with:
                  version: 8
                  run_install: false

            - name: "Set node version to ${{ matrix.node_version }}"
              uses: "actions/setup-node@v3"
              with:
                  node-version: "${{ matrix.node_version }}"
                  cache: "pnpm"

            - name: "Check npm version"
              run: "npm -v"
              env:
                  SKIP_CHECK: "true"

            - name: "Install packages"
              run: "pnpm install --frozen-lockfile"
              env:
                  SKIP_CHECK: "true"

            # - name: "Build"
            #   run: "pnpm run build:packages"

            # - name: "test and coverage"
            #   run: "pnpm run test:coverage"

    semantic-release:
        name: "Semantic Release"

        runs-on: "ubuntu-latest"

        needs: ["test", "eslint"]

        steps:
            - name: "Git checkout"
              uses: "actions/checkout@v3"
              with:
                  fetch-depth: 0
                  persist-credentials: false
              env:
                  GIT_COMMITTER_NAME: "GitHub Actions Shell"
                  GIT_AUTHOR_NAME: "GitHub Actions Shell"
                  EMAIL: "github-actions[bot]@users.noreply.github.com"

            - uses: "pnpm/action-setup@v2.2.4"
              with:
                  version: 8
                  run_install: false

            - name: "Use Node.js 16.x"
              uses: "actions/setup-node@v3"
              with:
                  node-version: "16.x"
                  cache: "pnpm"

            - name: "Check npm version"
              run: "npm -v"
              env:
                  SKIP_CHECK: "true"

            - name: "Install packages"
              run: "pnpm install --frozen-lockfile"

            # - name: "Build Production"
            #   run: "pnpm run build:prod:packages"

            - name: "npm v8.5+ requires workspaces-update to be set to false"
              run: "echo 'workspaces-update=false' >> .npmrc"

            - name: "Semantic Release"
              if: "success()"
              env:
                  GITHUB_TOKEN: "${{ secrets.SEMANTIC_RELEASE_GITHUB_TOKEN }}"
                  NPM_TOKEN: "${{ secrets.NPM_AUTH_TOKEN }}"
                  GIT_AUTHOR_NAME: "github-actions-shell"
                  GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
                  GIT_COMMITTER_NAME: "github-actions-shell"
                  GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
              run: "pnpm exec multi-semantic-release"

    pnpm-lock-update:
        name: "pnpm-lock.yaml update"

        runs-on: "ubuntu-latest"

        needs: ["semantic-release"]

        steps:
            - name: "Git checkout"
              uses: "actions/checkout@v3"
              with:
                  fetch-depth: 2
              env:
                  GIT_COMMITTER_NAME: "GitHub Actions Shell"
                  GIT_AUTHOR_NAME: "GitHub Actions Shell"
                  EMAIL: "github-actions[bot]@users.noreply.github.com"

            - uses: "pnpm/action-setup@v2.2.4"
              with:
                  version: 8

            - name: "Use Node.js 16.x"
              uses: "actions/setup-node@v3"
              with:
                  node-version: "16.x"

            - name: "Update pnpm lock"
              run: "pnpm install --no-frozen-lockfile"

            - name: "Commit modified files"
              uses: "stefanzweifel/git-auto-commit-action@v4.16.0"
              with:
                  commit_message: "chore: updated pnpm-lock.yaml"
                  commit_author: "prisis <d.bannert@anolilab.de>"
                  commit_user_email: "d.bannert@anolilab.de"
                  commit_user_name: "prisis"
                  branch: "${{ github.head_ref }}"

Note on GitHub protected branches

If you’re releasing a GitHub protected branch you need to change the git committer to an owner/admin and allow repo admins to bypass the branch protection (make sure "include administrators" is disabled in the branch protection rules.)

If your repo is under an organisation, you can create a bot account and give it admin rights on the repo. If your repo is under a personal account, you have no choice to make the repo owner the commiter for the release.

Either way, you have to create a GitHub personal access token for the committer account and give it the "repo" access rights. Then set it to the GH_TOKEN secret in your GitHub repository.

Note: GitHub secrets not shared with forks and pull requests, so no one that doesn’t have write access to your repo can use of them.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

Daniel Bannert
All Contributors

License

The anolilab javascript-style-guide is open-sourced software licensed under the MIT license

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!