@schroedernet/semantic-release-config v1.0.0-alpha.7

@schroedernet/semantic-release-config

Opinionated configuration for semantic-release.

• Overview
• Usage
• Installation
• Configuration
  • GitHub
  • GitLab
  • Git
  • Npm
• Security considerations
  • Access tokens
  • Hosting sites
  • GPG keys

Overview

This configuration aims to support best practices by keeping a changelog with signed commits alongside source code, and to "just work" for simple projects based on the environment that provides the context in which it is run.

Usage

When the configuration is first loaded by semantic-release, the exact list of plugins to be used is determined by the environment (variables). If a plugin requires configuration or only makes sense in certain contexts, it is not loaded unless relevant environment variables are present. This makes it possible to mix and match plugins with a single configuration, potentially making code more portable, particularly with regard to hosting sites, CI/CD, and mirroring.

For example, it is possible to have a project set up to be hosted on gitlab.com, where packaging and changelog updating occurs, mirrored to both github.com and a private GitLab instance, and still have "releases" created at all three locations. I.e.:

• gitlab.com
  • Canonical "source of truth"
  • Updates changelog file
  • Packages code, e.g. for npm
  • Creates "release" on gitlab.com with most recent changes in description
• github.com
  • Mirror
  • Creates "release" on github.com with most recent changes in description
• Private GitLab instance
  • Mirror
  • Creates "release" on private GitLab instance with most recent changes in description

See Configuration for a full list of supported plugins.

Installation

1. Install @schroedernet/semantic-release-config as development dependency
   • npm install -D @schroedernet/semantic-release-config
2. Add to extends array in .releaserc
   • {extends: ['@schroedernet/semantic-release-config']}

Configuration

The full list of supported plugins (in order of possible execution), of which a subset will run (determined at run-time based on environment configuration) is:

1. @semantic-release/commit-analyzer
   • Analyze commits with conventional-changelog
   • Required; always loaded
2. @semantic-release/release-notes-generator
   • Generate changelog content with conventional-changelog
   • Required; always loaded
3. @semantic-release/changelog
   • Create or update a changelog file
   • Required; always loaded
4. @semantic-release/npm
   • Publish a npm package
   • Conditional; see detailed description
5. @semantic-release/git
   • Commit release assets to the project's git repository
   • Conditional; see detailed description
6. @semantic-release/github
   • Publish a GitHub release and comment on released Pull Requests/Issues
   • Conditional; see detailed description
7. @semantic-release/gitlab
   • Publish a GitLab release
   • Conditional; see detailed description

GitHub

The @semantic-release/github plugin will be loaded automatically when run in the context of GitHub Actions.

Required environment variables:

• GITHUB_ACTIONS
  • Set by GitHub Actions to let programs know they are running in GitHub Actions
• GITHUB_TOKEN/GH_TOKEN
  • OAuth token for interacting with GitHub's Releases API
  • The simplest method is to re-use the GITHUB_TOKEN variable provided by the GitHub Actions environment if you are fine with releases being created by the default github-actions user. This can be done by adding GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} to the env key of the release step in the worflow yaml file.
  • Alternatively, a different OAuth token with repo scope can be provided to create the release with a custom user. It is recommended to use the GH_TOKEN variable for this so as to avoid conflict with the reserved GITHUB_ namespace for environment variables provided by GitHub Actions.

GitLab

The @semantic-release/gitlab plugin will be loaded automatically when run in the context of GitLab CI.

Required environment variables:

• GITLAB_CI
  • Set by GitLab CI to let programs know they are running in GitLab CI
• GITLAB_TOKEN/GL_TOKEN
  • OAuth token for interacting with GitLab's Releases API
  • A personal access token with api scope is required. Alternatively, a project access token may be used.

Git

The @semantic-release/git plugin will be loaded when the required environment variables are set.

Required environment variables:

• GIT_GPG_KEY_ID
  • ID of the GPG key to use for signing commits
  • Must be available in the keys provided by GIT_GPG_KEYS
• GIT_GPG_KEYS
  • Exported public and private GPG keys to use for signing commits
  • Must be base64 encoded so GitLab can properly mask the value
  • Example export command:
    • echo "$(gpg --armor --export && gpg --armor --export-secret-keys)" | base64 -w 0
  • See Secutiy considerations
• GITHUB_TOKEN/GH_TOKEN/GITLAB_TOKEN
  • OAuth token with push access to the repository
  • This is the same as what semantic-release already requires for authentication to create git tags.

Optional environment variables:

• GIT_AUTHOR_NAME
  • The author name associated with the release commit
  • See Git environment variables
• GIT_AUTHOR_EMAIL
  • The author email associated with the release commit
  • See Git environment variables
• GIT_COMMITER_NAME
  • The commiter name associated with the release commit
  • See Git environment variables
• GIT_COMMITER_EMAIL
  • The commiter email associated with the release commit
  • See Git environment variables

Npm

The @semantic-release/npm plugin will be loaded when the required environment variables are set.

Required environment variables:

• NPM_TOKEN
  • Access token for interacting with npm
  • The token should be of "automation" type

Security considerations

Disclaimer: The following are recommended considerations. There is no "one size fits all" solution to security and it is important that appropriate consideration also be given to the context of the individual problem to be solved.

Access tokens

Using a "bot" account (as opposed to an account designated to a human) for automation tasks reduces risk by limiting the capabilities of potential attackers in the event the secret is exposed. This also has the benefit of separating people from infrastructure.

Limiting the scope of access tokens to cover only required permissions reduces risk by limiting the capabilities of potential attackers in the event the secret is exposed. See Configuration details for what scopes are relevant and when.

Avoiding token re-use reduces risk both by limiting the capabilities of potential attackers in the event the secret is exposed and by limiting exposure to a particular secret. This also has the benefit of simplifying the process of revoking and/or updating a particular token by limiting the number of places it is used.

Hosting sites

Limiting project collaborator permissions to only what is required reduces risk by limiting secret exposure. This also has the benefit of reducing attack/abuse potential in the event a collaborator's credentials are abused.

Using protected branches/tags/etc reduces risk by limiting secret exposure. This also has the benefit of keeping potentially untested or unreviewed code away from potentially sensitive APIs.

GPG keys

Using subkeys reduces risk by limiting (master) secret exposure. This also has the benefit of being able to keep the master key offline and more strongly secured since the master key is only required for creating or modifying the subkey.

Avoiding key re-use reduces risk by limiting secret exposure. This also has the benefit of simplifying the process of revoking and/or updating a particular key by limiting the number of places it is used, and is made easier by the fact that any given key can produce an unlimited number of subkeys.

Using ECC over RSA has possible advantages such as reduced key and signature length. It also has the possible benefit of offering implementation designs by more "independent" entities.