From 1405b94296059c0c6878fb8b626e2c5da9317632 Mon Sep 17 00:00:00 2001 From: kopal <50901044+kopal2212@users.noreply.github.com> Date: Wed, 1 Jul 2020 03:24:33 +0530 Subject: [PATCH 01/11] docs: added recipe for Jenkins CI configuration (#1) (#1591) --- docs/recipes/README.md | 1 + docs/recipes/jenkins-ci.md | 61 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/recipes/jenkins-ci.md diff --git a/docs/recipes/README.md b/docs/recipes/README.md index b8ed74756f..7d3d906848 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -5,6 +5,7 @@ - [Travis CI](travis.md) - [GitLab CI](gitlab-ci.md) - [GitHub Actions](github-actions.md) +- [Jenkins CI](jenkins-ci.md) ## Git hosted services - [Git authentication with SSH keys](git-auth-ssh-keys.md) diff --git a/docs/recipes/jenkins-ci.md b/docs/recipes/jenkins-ci.md new file mode 100644 index 0000000000..5472a7eecc --- /dev/null +++ b/docs/recipes/jenkins-ci.md @@ -0,0 +1,61 @@ +# Using semantic-release with [Jenkins CI](https://www.jenkins.io/doc/book/pipeline/) + +## Environment variables + +The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/).. + +Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started). + +## Node.js project configuration + +### `Jenkinsfile (Declarative Pipeline)` configuration for a Node.js job + +**Note**: The publish pipeline must run a [Node >= 10.18 version](../support/FAQ.md#why-does-semantic-release-require-node-version--1018). + +This example is a minimal configuration for **semantic-release** with a build running Node 10.18. See [Jenkins documentation](https://www.jenkins.io/doc/) for additional configuration options. + +The`semantic-release` execution command varies depending if you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) **semantic-release** installation. + +```yaml +// The release stage in the pipeline will run only if the test stage in the pipeline is successful +pipeline { + agent any + environment { + GH_TOKEN = credentials('some-id') + } + stages { + stage('Test') { + steps { + sh ''' + # Configure your test steps here (checkout, npm install, tests etc) + npm install + npm test + ''' + } + } + stage('Release') { + tools { + nodejs "node 10.18" + } + steps { + sh ''' + # Run optional required steps before releasing + npx semantic-release + ''' + } + } + } +} +``` + +### `package.json` configuration for a Node job + +A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation. + +```json +{ + "devDependencies": { + "semantic-release": "^15.0.0" + } +} +``` \ No newline at end of file From b5c9dea21503a2bcd2c4d639aded89dde6c8438d Mon Sep 17 00:00:00 2001 From: Shun Kakinoki <39187513+shunkakinoki@users.noreply.github.com> Date: Fri, 10 Jul 2020 09:58:09 +0900 Subject: [PATCH 02/11] docs: update github documentation to `docs.github.com` --- docs/usage/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md index d21c93fbe4..536faf43d6 100644 --- a/docs/usage/configuration.md +++ b/docs/usage/configuration.md @@ -74,7 +74,7 @@ The branches on which releases should happen. By default **semantic-release** wi **Note**: If your repository does not have a release branch, then **semantic-release** will fail with an `ERELEASEBRANCHES` error message. If you are using the default configuration, you can fix this error by pushing a `master` branch. -**Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://help.github.com/articles/about-protected-branches). +**Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://docs.github.com/github/administering-a-repository/about-protected-branches). See [Workflow configuration](workflow-configuration.md#workflow-configuration) for more details. From 6d118c6c1433cb713eddd0e7cb0f0baffa11e4a0 Mon Sep 17 00:00:00 2001 From: Gavin Staniforth Date: Sun, 12 Jul 2020 20:31:40 +0100 Subject: [PATCH 03/11] docs: be clear about what module of semantic-release handles updating the package.json (#1601) --- docs/support/FAQ.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/support/FAQ.md b/docs/support/FAQ.md index 3c548213e6..180177a06c 100644 --- a/docs/support/FAQ.md +++ b/docs/support/FAQ.md @@ -2,12 +2,14 @@ ## Why is the `package.json`’s version not updated in my repository? -**semantic-release** takes care of updating the `package.json`’s version before publishing to [npm](https://www.npmjs.com). +[`@semantic-release/npm`](https://github.com/semantic-release/npm) takes care of updating the `package.json`’s version before publishing to [npm](https://www.npmjs.com). By default, only the published package will contain the version, which is the only place where it is *really* required, but the updated `package.json` will not be pushed to the Git repository However, the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used to push the updated `package.json` as well as other files to the Git repository. +If you wish to only update the `package.json` and push via Git you can set the project to `"private": true,` within your `package.json` to prevent publishing to [npm](https://www.npmjs.com). This can be useful for using **semantic-release** with a non-node project. + ## How can I use a npm build script that requires the `package.json`’s version ? The `package.json`’s version will be updated by the `semantic-release` command just before publishing to [npm](https://www.npmjs.com), therefore it won't be available for scripts ran before the `semantic-release` command. From b24d2474b1cfd49e1e29b31044038bfee921c003 Mon Sep 17 00:00:00 2001 From: Rylan Collins Date: Wed, 22 Jul 2020 16:35:05 -0700 Subject: [PATCH 04/11] docs: add `semantic-release-rubygem` to community plugins (#1602) --- docs/extending/plugins-list.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/extending/plugins-list.md b/docs/extending/plugins-list.md index d5c47a3bd0..54486065b6 100644 --- a/docs/extending/plugins-list.md +++ b/docs/extending/plugins-list.md @@ -101,3 +101,7 @@ - `addChannel`: Update a Gitea release's pre-release field. - [@google/semantic-release-replace-plugin](https://github.com/google/semantic-release-replace-plugin) - `prepare`: Replace version strings in files using regex and glob. +- [semantic-release-rubygem](https://github.com/Gusto/semantic-release-rubygem) + - `verifyConditions`: Locate and validate a `.gemspec` file, locate and validate a `lib/**/version.rb` file, verify the presence of the `GEM_HOST_API_KEY` environment variable, and create a credentials file with the API key. + - `prepare`: Update the version in the `lib/**/version.rb` version file and [build](https://guides.rubygems.org/command-reference/#gem-build) the gem. + - `publish`: [Push the Ruby gem](https://guides.rubygems.org/command-reference/#gem-push) to the gem server. From ee44ee80c875c3131ffd8148b136ca46ae394b35 Mon Sep 17 00:00:00 2001 From: Ahmed Hassanein Date: Tue, 28 Jul 2020 15:57:05 +0200 Subject: [PATCH 05/11] docs(github-actions): suggest action_dispatch as trigger (#1605) --- docs/recipes/github-actions.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/recipes/github-actions.md b/docs/recipes/github-actions.md index 80a9414580..25051188f3 100644 --- a/docs/recipes/github-actions.md +++ b/docs/recipes/github-actions.md @@ -50,7 +50,11 @@ To keep `package.json` updated in the `master` branch, [`@semantic-release/git`] ## Trigger semantic-release on demand -There is a way to trigger semantic-relase on demand. Use [`repository_dispatch`](https://help.github.com/en/articles/events-that-trigger-workflows#external-events-repository_dispatch) event to have control on when to generate a release by making an HTTP request, e.g.: +### Using GUI: +You can use [Manual Triggers](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/) for GitHub Actions. + +### Using HTTP: +Use [`repository_dispatch`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#repository_dispatch) event to have control on when to generate a release by making an HTTP request, e.g.: ```yaml name: Release @@ -67,6 +71,7 @@ To trigger a release, call (with a [Personal Access Tokens](https://help.github. $ curl -v -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/repos/[org-name-or-username]/[repository]/dispatches -d '{ "event_type": "semantic-release" }' ``` +### Using 3rd party apps: If you'd like to use a GitHub app to manage this instead of creating a personal access token, you could consider using a project like: * [Actions Panel](https://www.actionspanel.app/) - A declaratively configured way for triggering GitHub Actions From b72cdb331b6db057ec0f44cf4f6a281726075f3b Mon Sep 17 00:00:00 2001 From: kopal <50901044+kopal2212@users.noreply.github.com> Date: Thu, 30 Jul 2020 03:55:32 +0530 Subject: [PATCH 06/11] docs(configuration.md): Updated documentation for dry-run feature of semantic Release (#1607) --- docs/usage/configuration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md index 536faf43d6..38e2213cde 100644 --- a/docs/usage/configuration.md +++ b/docs/usage/configuration.md @@ -116,7 +116,9 @@ Type: `Boolean`
Default: `false` if running in a CI environment, `true` otherwise
CLI arguments: `-d`, `--dry-run` -Dry-run mode, skip publishing, print next version and release notes. +The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following steps: prepare, publish, success and fail. In addition to this it prints the next version and release notes to the console. + +**Note**: The Dry-run mode verifies the repository push permission, even though nothing will be pushed. The verification is done to help user to figure out potential configuration issues. ### ci From 9303d1dba0790fb765ae46625d8e7fdecbf6ffe6 Mon Sep 17 00:00:00 2001 From: AbdelRahman Wahdan Date: Fri, 31 Jul 2020 02:17:36 +0200 Subject: [PATCH 07/11] docs(resources.md): added more sematnic release article (#1610) --- docs/support/resources.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/support/resources.md b/docs/support/resources.md index b426833ac9..830ef483aa 100644 --- a/docs/support/resources.md +++ b/docs/support/resources.md @@ -14,6 +14,7 @@ - ["Introduction to SemVer" - Irina Gebauer](https://blog.greenkeeper.io/introduction-to-semver-d272990c44f2) - ["Introduction to Semantic Release" - liv](https://blog.greenkeeper.io/introduction-to-semantic-release-33f73b117c8) +- ["Series - Semantic Release Automation" - Abdelrahman Wahdan](https://dev.to/abdelrahmanahmed/semantic-release-and-how-to-automate-it-part-1-4pa2) ## Tutorials From d036a899d51568d616ecff7fc11ffc483d5bfabf Mon Sep 17 00:00:00 2001 From: ylemkimon Date: Tue, 18 Aug 2020 08:26:13 +0900 Subject: [PATCH 08/11] ci(docs): use actions/checkout@v2 (#1620) --- docs/recipes/github-actions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/recipes/github-actions.md b/docs/recipes/github-actions.md index 25051188f3..6116ef1d13 100644 --- a/docs/recipes/github-actions.md +++ b/docs/recipes/github-actions.md @@ -28,7 +28,9 @@ jobs: runs-on: ubuntu-18.04 steps: - name: Checkout - uses: actions/checkout@v1 + uses: actions/checkout@v2 + with: + fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v1 with: From 9635f50da67f252ef1d495d8b2c7cc3a7cde717c Mon Sep 17 00:00:00 2001 From: Joep Kockelkorn Date: Sun, 6 Sep 2020 19:38:29 +0200 Subject: [PATCH 09/11] docs: improve github actions recipe on git plugin (#1626) --- docs/recipes/github-actions.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/recipes/github-actions.md b/docs/recipes/github-actions.md index 6116ef1d13..4f1f356f3d 100644 --- a/docs/recipes/github-actions.md +++ b/docs/recipes/github-actions.md @@ -50,6 +50,16 @@ To keep `package.json` updated in the `master` branch, [`@semantic-release/git`] **Note**: Automatically populated `GITHUB_TOKEN` cannot be used if branch protection is enabled for the target branch. It is **not** advised to mitigate this limitation by overriding an automatically populated `GITHUB_TOKEN` variable with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line), as it poses a security risk. Since Secret Variables are available for Workflows triggered by any branch, it becomes a potential vector of attack, where a Workflow triggered from a non-protected branch can expose and use a token with elevated permissions, yielding branch protection insignificant. One can use Personal Access Tokens in trusted environments, where all developers should have the ability to perform administrative actions in the given repository and branch protection is enabled solely for convenience purposes, to remind about required reviews or CI checks. +If the risk is acceptible, some extra configuration is needed. The [actions/checkout `persist-credentials`](https://github.com/marketplace/actions/checkout#usage) option needs to be `false`, otherwise the generated `GITHUB_TOKEN` will interfere with the custom one. Example: + +```yaml +- name: Checkout + uses: actions/checkout@v2 + with: + fetch-depth: 0 + persist-credentials: false # <--- this +``` + ## Trigger semantic-release on demand ### Using GUI: From c982249f876b0ec5109ad90ad110093fcbecd896 Mon Sep 17 00:00:00 2001 From: Micael Jarniac Date: Wed, 16 Sep 2020 15:39:04 -0300 Subject: [PATCH 10/11] docs(contributing): typo fix (#1638) --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8802ead580..ac3f91464d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,11 +107,11 @@ To ensure consistency and quality, all documentation modifications must: - a third-party product/brand/service, i.e. Integrate with [GitHub](https://github.com) - an external concept or feature, i.e. Create a [GitHub release](https://help.github.com/articles/creating-releases) - a package or module, i.e. The [`@semantic-release/github`](https://github.com/semantic-release/github) module -- Use the the [single backtick `code` quoting](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) for: +- Use the [single backtick `code` quoting](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) for: - commands inside sentences, i.e. the `semantic-release` command - programming language keywords, i.e. `function`, `async`, `String` - packages or modules, i.e. The [`@semantic-release/github`](https://github.com/semantic-release/github) module -- Use the the [triple backtick `code` formatting](https://help.github.com/articles/creating-and-highlighting-code-blocks) for: +- Use the [triple backtick `code` formatting](https://help.github.com/articles/creating-and-highlighting-code-blocks) for: - code examples - configuration examples - sequence of command lines From b4c5d0a436fa5a4e98d8326f0512fa8a2f1f4f67 Mon Sep 17 00:00:00 2001 From: Tom Williams Date: Thu, 17 Sep 2020 10:15:04 -0700 Subject: [PATCH 11/11] fix: add logging for when ssh falls back to http (#1639) Co-authored-by: thomas williams --- lib/get-git-auth-url.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/get-git-auth-url.js b/lib/get-git-auth-url.js index fe251d90b7..2ebb84a10b 100644 --- a/lib/get-git-auth-url.js +++ b/lib/get-git-auth-url.js @@ -2,6 +2,7 @@ const {parse, format} = require('url'); // eslint-disable-line node/no-deprecate const {isNil} = require('lodash'); const hostedGitInfo = require('hosted-git-info'); const {verifyAuth} = require('./git'); +const debug = require('debug')('semantic-release:get-git-auth-url'); /** * Determine the the git repository URL to use to push, either: @@ -42,8 +43,11 @@ module.exports = async ({cwd, env, branch, options: {repositoryUrl}}) => { // Test if push is allowed without transforming the URL (e.g. is ssh keys are set up) try { + debug('Verifying ssh auth by attempting to push to %s', repositoryUrl); await verifyAuth(repositoryUrl, branch.name, {cwd, env}); } catch (_) { + debug('SSH key auth failed, falling back to https.'); + const envVar = Object.keys(GIT_TOKENS).find((envVar) => !isNil(env[envVar])); const gitCredentials = `${GIT_TOKENS[envVar] || ''}${env[envVar] || ''}`;