Semantic Release Configuration

A shareable semantic release configuration supporting a range of languages and platforms I tend to work in.

Features

• Analyzes commits using @semantic-release/commit-analyzer.
• Generates release notes using @semantic-release/release-notes-generator.
• Updates templated content in a project's root-level README.md file with updated version information using @google/semantic-release-replace-plugin and @semantic-release/git.
• Maintains a CHANGELOG.md from the generated release notes using @semantic-release/changelog and @semantic-release/git.
• (Conditionally) maintains NPM package files, i.e. package.json and publishes using @semantic-release/npm and @semantic-release/git.
• Publishes releases to GitLab using @semantic-release/gitlab.

Usage

• Create a personal access token, with api and write_repository scopes. Make the token available as a GITLAB_TOKEN or GL_TOKEN CI/CD variable of the project using the configuration.

  For improved security, use a unique token for every project this configuration is used in!

• Use this shareable semantic release configuration by including it in the extends configuration for the project to be semantically released.

JavaScript Packages

JavaScript packages are detected based on the presence of a package.json file in the root of the project.

• Create an NPM token to be able to publish to an NPM registry. Make the token available as an NPM_TOKEN CI/CD variable of the project using the configuration.

  See the plugin's configuration instructions for details and alternatives.

Templated Content in README.md Files

The configuration will look for __NEXT_SEMANTIC_RELEASE_VERSION__ tokens in templates in a project's root-level README.md and replace them with the version that is being released. This is, for instance, useful for automatically keeping installation instructions up-to-date.

Templated content is created using HTML comments and has the following structure:

• A <!-- START_VERSIONED_TEMPLATE token,
• the template itself with one or more __NEXT_SEMANTIC_RELEASE_VERSION__ tokens,
• a comment closing tag -->,
• (optionally) content that was previously templated,
• a comment closing the templated content <!-- END_VERSIONED_TEMPLATE -->.

More concretely a section in a README that looks like

<!-- START_VERSIONED_TEMPLATE

The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!

-->
<!-- END_VERSIONED_TEMPLATE -->

would, after a v1.2.3 release using the configuration has been triggered, become

<!-- START_VERSIONED_TEMPLATE

The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!

-->

The next semantically released version will be v1.2.3!

<!-- END_VERSIONED_TEMPLATE -->

Note that the v is in the template! The version as derived by the semantic release tooling does not contain that prefix.

Troubleshooting

Publishing the initial release of a scoped JavaScript package

Creating the initial release of a scoped JavaScript may fail if the package is intended to be public and the person creating the release not having paid for private packages. This results in an error similar to

npm ERR! 402 Payment Required - PUT https://registry.npmjs.org/@<scope>%2f<package-name> -
You must sign up for private packages

When this happens, publish the initial release manually using npm publish --access=public after making sure the local copy of the project to be released is up-to-date.

When this happens, it is typically also necessary to create the initial GitHub release by hand from the tag and changelog that was created by the semantic-release tooling.