@ethima/semantic-release-configuration 3.0.0 → 3.2.0

package/README.md

@@ -7,7 +7,10 @@ configuration supporting a range of languages and platforms supported by the
 ## Features
 
 - Analyzes commits using
-  [`@semantic-release/commit-analyzer`][semantic-release-commit-analyzer-plugin-url].
+  [`@semantic-release/commit-analyzer`][semantic-release-commit-analyzer-plugin-url]
+  and the [`conventional-changelog-conventionalcommits`
+  preset][conventionalcommits-preset-url] implementing the [Conventional
+  Commits specification][conventionalcommits-url].
 - Generates release notes using
   [`@semantic-release/release-notes-generator`][semantic-release-notes-generator-plugin-url].
 - Updates templated content in a project's root-level `README.md` file
@@ -20,14 +23,18 @@ configuration supporting a range of languages and platforms supported by the
 - (Conditionally) maintains NPM package files, i.e. `package.json` and
   publishes using [`@semantic-release/npm`][semantic-release-npm-plugin-url]
   and [`@semantic-release/git`][semantic-release-git-plugin-url].
-- Publishes releases to GitLab using
-  [`@semantic-release/gitlab`][semantic-release-gitlab-plugin-url].
+- Publishes releases to the relevant hosting platform, i.e. GitHub or GitLab,
+  using the platform-specific release plugins
+  [`@semantic-release/github`][semantic-release-github-plugin-url] or
+  [`@semantic-release/gitlab`][semantic-release-gitlab-plugin-url]
+  respectively.
 
 ## Usage
 
-- Create a [personal access token][gitlab-pat-url], 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.
+- Create the relevant secret token for the platform on which the project
+  using this configuration is hosted, e.g. `GH_TOKEN`, `GITLAB_TOKEN`. The
+  supported platforms are [GitHub][semantic-release-github-plugin-auth-url] and
+  [GitLab][semantic-release-gitlab-plugin-auth-url].
 
   For improved security, _use a unique token for every project this
   configuration is used in_!
@@ -36,11 +43,16 @@ configuration supporting a range of languages and platforms supported by the
   [`extends`][semantic-release-extends-configuration-url] configuration for the
   project to be semantically released.
 
+- When using this shareable semantic release configuration on GitHub, be sure
+  to read the instructions below on the `primary_release_branch` configuration
+  and provide an appropriate value if necessary.
+
 ### Configuration
 
 The semantic release configuration has several configuration options itself.
-Some of this configuration, like sensitive tokens such as `GITLAB_TOKEN` and
-`NPM_TOKEN`, should be configured through environment variables.
+Some of this configuration, like sensitive tokens such as `GH_TOKEN`,
+`GITLAB_TOKEN` and `NPM_TOKEN`, should be configured through environment
+variables.
 
 Other configuration options have more complex values and are not suitable for
 configuration through environment variables. These configuration options can be
@@ -49,7 +61,15 @@ for this purpose. This library will search for an `ethima` configuration file
 as explained in the introduction of its `README`, e.g. a JSON or YAML-formatted
 `.ethimarc` or `.config/ethimarc` file, JavaScript in a `.ethimarc.js`, etc.
 
-All configuration options are explained in more detail in the sections
+Generic configuration options are:
+
+- `primary_release_branch` a string indicating the "primary" release branch,
+  i.e. the branch from which new releases should be created. This may also be
+  specified as a `PRIMARY_RELEASE_BRANCH` environment variable and will default
+  to [the `CI_DEFAULT_BRANCH` on GitLab][gitlab-predefined-variables-url] and
+  to `main` on other platforms.
+
+Other configuration options are explained in more detail in the sections
 describing the functionality they apply to.
 
 ### Changelog Maintenance
@@ -177,15 +197,20 @@ 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`][semantic-release-url] tooling.
 
+[conventionalcommits-url]: https://www.conventionalcommits.org
+[conventionalcommits-preset-url]: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits
 [cosmiconfig-url]: https://www.npmjs.com/package/cosmiconfig
-[gitlab-pat-url]: https://gitlab.com/-/profile/personal_access_tokens
+[gitlab-predefined-variables-url]: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
 [npm-token-url]: https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website
 [replace-in-file-url]: https://www.npmjs.com/package/replace-in-file
 [semantic-release-changelog-plugin-url]: https://github.com/semantic-release/changelog
 [semantic-release-commit-analyzer-plugin-url]: https://github.com/semantic-release/commit-analyzer
 [semantic-release-extends-configuration-url]: https://semantic-release.gitbook.io/semantic-release/usage/configuration#extends
 [semantic-release-git-plugin-url]: https://github.com/semantic-release/git
+[semantic-release-github-plugin-url]: https://github.com/semantic-release/github
+[semantic-release-github-plugin-auth-url]: https://github.com/semantic-release/github#github-authentication
 [semantic-release-gitlab-plugin-url]: https://github.com/semantic-release/gitlab
+[semantic-release-gitlab-plugin-auth-url]: https://github.com/semantic-release/gitlab#gitlab-authentication
 [semantic-release-notes-generator-plugin-url]: https://github.com/semantic-release/release-notes-generator
 [semantic-release-npm-plugin-configuration-url]: https://github.com/semantic-release/npm#npm-registry-authentication
 [semantic-release-npm-plugin-url]: https://www.npmjs.com/package/@semantic-release/npm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethima/semantic-release-configuration",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "A shareable semantic release configuration supporting a range of languages and platforms supported by the Ethima organization.",
   "main": "./src/index.js",
   "repository": {
@@ -21,6 +21,7 @@
     "@google/semantic-release-replace-plugin": "1.2.0",
     "@semantic-release/changelog": "6.0.2",
     "@semantic-release/git": "10.0.1",
+    "@semantic-release/github": "8.0.7",
     "@semantic-release/gitlab": "9.5.1",
     "conventional-changelog-conventionalcommits": "5.0.0",
     "cosmiconfig": "8.0.0"

package/src/configuration.js

@@ -1,8 +1,15 @@
 const { cosmiconfigSync } = require("cosmiconfig");
+const { env } = require("node:process");
 
 const CONFIGURATION_DEFAULTS = {
   changelog_filename: "CHANGELOG.md",
   files_with_versioned_templates: ["README.md"],
+  // The `PRIMARY_RELEASE_BRANCH` environment variable is used as a platform
+  // independent mechanism for specifying the primary release branch. On GitLab
+  // this defaults to the "default" branch. Given that the "default" branch is
+  // not readily available on GitHub `main` is used as a fallback
+  primary_release_branch:
+    env.PRIMARY_RELEASE_BRANCH || env.CI_DEFAULT_BRANCH || "main",
 };
 
 const ethimaConfig = cosmiconfigSync("ethima").search();

package/src/index.js

@@ -9,6 +9,27 @@ const GIT_ASSETS = [
   ...CONFIGURATION.files_with_versioned_templates,
 ];
 
+// Used to detect whether configuration for either the
+// `semantic-release/github`, `semantic-release/gitlab` or both platform
+// release plugins has been provided through the environment
+const GITHUB_TOKEN_NAMES = ["GH_TOKEN", "GITHUB_TOKEN"];
+const GITLAB_TOKEN_NAMES = ["GL_TOKEN", "GITLAB_TOKEN"];
+
+/*
+ * Determines whether the provided plugin should be added to the semantic
+ * release configuration based on the presence of select environment variables.
+ *
+ * @param {Array} token_names An array of strings specifying the names of the
+ * environment variables to detect.
+ * @param {string} plugin The name of the NPM package providing the plugin.
+ *
+ * @return {Array} References the plugin if any of the `token_names` are
+ * detected and is empty otherwise.
+ */
+function platformSpecificReleasePlugin(token_names, plugin) {
+  return token_names.some((token_name) => env[token_name]) ? [plugin] : [];
+}
+
 // Ensure the NPM plugin gets added to the semantic release pipeline if a
 // `package.json` file is detected
 const NPM_PLUGIN = [];
@@ -19,7 +40,7 @@ try {
 } catch {}
 
 const SEMANTIC_RELEASE_CONFIGURATION = {
-  branches: [env.CI_DEFAULT_BRANCH],
+  branches: [CONFIGURATION.primary_release_branch],
   plugins: [
     ["@semantic-release/commit-analyzer", { preset: "conventionalcommits" }],
     "@semantic-release/release-notes-generator",
@@ -42,7 +63,14 @@ const SEMANTIC_RELEASE_CONFIGURATION = {
           "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}",
       },
     ],
-    "@semantic-release/gitlab",
+    ...platformSpecificReleasePlugin(
+      GITHUB_TOKEN_NAMES,
+      "semantic-release/github"
+    ),
+    ...platformSpecificReleasePlugin(
+      GITLAB_TOKEN_NAMES,
+      "semantic-release/gitlab"
+    ),
   ],
 };