semantic-release 25.0.4 → 25.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -37
- package/bin/semantic-release.js +1 -1
- package/index.js +265 -37
- package/lib/branches/expand.js +18 -0
- package/lib/branches/get-tags.js +39 -0
- package/lib/branches/index.js +71 -0
- package/lib/branches/normalize.js +104 -0
- package/lib/definitions/branches.js +22 -0
- package/lib/definitions/constants.js +8 -9
- package/lib/definitions/errors.js +303 -0
- package/lib/definitions/plugins.js +108 -0
- package/lib/get-commits.js +31 -0
- package/lib/get-config.js +98 -0
- package/lib/get-error.js +7 -0
- package/lib/get-git-auth-url.js +126 -0
- package/lib/get-last-release.js +48 -0
- package/lib/get-logger.js +19 -0
- package/lib/get-next-version.js +35 -0
- package/lib/get-release-to-add.js +59 -0
- package/lib/git.js +381 -0
- package/lib/hide-sensitive.js +14 -1
- package/lib/plugins/index.js +103 -0
- package/lib/plugins/normalize.js +69 -0
- package/lib/plugins/pipeline.js +59 -0
- package/lib/plugins/utils.js +81 -0
- package/lib/utils.js +101 -0
- package/lib/verify.js +43 -0
- package/package.json +20 -15
- package/docs/README.md +0 -7
- package/docs/developer-guide/README.md +0 -5
- package/docs/developer-guide/js-api.md +0 -294
- package/docs/developer-guide/plugin.md +0 -284
- package/docs/developer-guide/shareable-configuration.md +0 -1
- package/docs/extending/README.md +0 -4
- package/docs/extending/plugins-list.md +0 -233
- package/docs/extending/shareable-configurations-list.md +0 -22
- package/docs/recipes/ci-configurations/README.md +0 -7
- package/docs/recipes/ci-configurations/circleci-workflows.md +0 -49
- package/docs/recipes/ci-configurations/github-actions.md +0 -136
- package/docs/recipes/ci-configurations/gitlab-ci.md +0 -98
- package/docs/recipes/ci-configurations/jenkins-ci.md +0 -61
- package/docs/recipes/ci-configurations/travis.md +0 -97
- package/docs/recipes/git-hosted-services/README.md +0 -3
- package/docs/recipes/git-hosted-services/git-auth-ssh-keys.md +0 -166
- package/docs/recipes/release-workflow/README.md +0 -5
- package/docs/recipes/release-workflow/distribution-channels.md +0 -117
- package/docs/recipes/release-workflow/maintenance-releases.md +0 -157
- package/docs/recipes/release-workflow/pre-releases.md +0 -197
- package/docs/support/FAQ.md +0 -253
- package/docs/support/README.md +0 -7
- package/docs/support/git-version.md +0 -4
- package/docs/support/node-support-policy.md +0 -21
- package/docs/support/node-version.md +0 -38
- package/docs/support/resources.md +0 -22
- package/docs/support/troubleshooting.md +0 -70
- package/docs/usage/README.md +0 -9
- package/docs/usage/ci-configuration.md +0 -50
- package/docs/usage/configuration.md +0 -206
- package/docs/usage/getting-started.md +0 -8
- package/docs/usage/installation.md +0 -51
- package/docs/usage/plugins.md +0 -105
- package/docs/usage/shareable-configurations.md +0 -7
- package/docs/usage/workflow-configuration.md +0 -199
|
@@ -1,136 +0,0 @@
|
|
|
1
|
-
# Using semantic-release with [GitHub Actions](https://help.github.com/en/categories/automating-your-workflow-with-github-actions)
|
|
2
|
-
|
|
3
|
-
## Environment variables
|
|
4
|
-
|
|
5
|
-
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets).
|
|
6
|
-
|
|
7
|
-
In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) is required to publish a package to the npm registry. GitHub Actions [automatically populate](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) a [`GITHUB_TOKEN`](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) environment variable which can be used in Workflows.
|
|
8
|
-
|
|
9
|
-
## Trusted publishing and npm provenance
|
|
10
|
-
|
|
11
|
-
For improved security and automation, it is recommended to leverage [trusted publishing](https://docs.npmjs.com/trusted-publishers) through [OpenID Connect (OIDC)](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) when publishing to npm from GitHub Actions.
|
|
12
|
-
GitHub Actions is a [trusted identity provider](https://docs.npmjs.com/trusted-publishers#identity-providers) for npm, enabling configuration of a trust relationship between your GitHub repository and npm so that no long-lived secret (like an `NPM_TOKEN`) is required to publish packages to npm from GitHub Actions.
|
|
13
|
-
The npm registry [recently increased restrictions for use of long-lived access tokens](https://github.blog/changelog/2025-09-29-strengthening-npm-security-important-changes-to-authentication-and-token-management/), further encouraging trusted publishing as the preferred approach for publishing to npm from GitHub Actions.
|
|
14
|
-
Enabling trusted publishing requires granting the `id-token: write` permission to the job performing the publish step and [configuring a trust relationship](https://docs.npmjs.com/trusted-publishers#step-1-add-a-trusted-publisher-on-npmjscom) between your GitHub repository and npm.
|
|
15
|
-
|
|
16
|
-
**Note**: When setting up a Trusted Publisher on npmjs for GitHub Actions, it's crucial to specify the workflow file that triggers the release process, not necessarily the one that contains the release logic itself.
|
|
17
|
-
If your release job is encapsulated in a [reusable workflow](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows), the workflow file you must reference is the caller workflow—typically the one triggered by events like `push` or `workflow_dispatch` on your main branch.
|
|
18
|
-
This is because npm's Trusted Publisher mechanism authorizes the workflow that initiates the run, not any downstream workflows it invokes.
|
|
19
|
-
|
|
20
|
-
[npm provenance](https://docs.npmjs.com/generating-provenance-statements) is valuable for increasing supply-chain security for your npm packages.
|
|
21
|
-
Before trusted publishing was available, generating provenance attestations required configuring your project to enable publishing with provenance.
|
|
22
|
-
With trusted publishing, npm provenance is automatically generated for packages published to npm from GitHub Actions without any additional configuration.
|
|
23
|
-
|
|
24
|
-
## Important: Avoid `registry-url` in `setup-node`
|
|
25
|
-
|
|
26
|
-
**Do not** set the `registry-url` option in the `actions/setup-node` step when using semantic-release for npm publishing. The `registry-url` option causes `setup-node` to create an `.npmrc` file that can conflict with semantic-release's npm authentication mechanism, leading to `EINVALIDNPMTOKEN` errors even when your token is valid.
|
|
27
|
-
|
|
28
|
-
```yaml
|
|
29
|
-
# ❌ Don't do this - can cause conflicts with semantic-release
|
|
30
|
-
- name: Setup Node.js
|
|
31
|
-
uses: actions/setup-node@v4
|
|
32
|
-
with:
|
|
33
|
-
node-version: "lts/*"
|
|
34
|
-
registry-url: "https://registry.npmjs.org"
|
|
35
|
-
|
|
36
|
-
# ✅ Do this instead - let semantic-release handle npm authentication
|
|
37
|
-
- name: Setup Node.js
|
|
38
|
-
uses: actions/setup-node@v4
|
|
39
|
-
with:
|
|
40
|
-
node-version: "lts/*"
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
If you need to specify a custom registry, configure it in your project's `.npmrc` file instead. This ensures consistent behavior between local development and CI environments, and avoids conflicts with semantic-release.
|
|
44
|
-
|
|
45
|
-
## Node project configuration
|
|
46
|
-
|
|
47
|
-
[GitHub Actions](https://github.com/features/actions) support [Workflows](https://help.github.com/en/articles/configuring-workflows), allowing to run tests on multiple Node versions and publish a release only when all test pass.
|
|
48
|
-
|
|
49
|
-
**Note**: The publish pipeline must run on a [Node version that meets our version requirement](../../support/node-version.md).
|
|
50
|
-
|
|
51
|
-
### `.github/workflows/release.yml` configuration for Node projects
|
|
52
|
-
|
|
53
|
-
The following is a minimal configuration for [`semantic-release`](https://github.com/semantic-release/semantic-release) with a build running on the latest LTS version of Node when a new commit is pushed to a `master/main` branch.
|
|
54
|
-
See the [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) for additional configuration options.
|
|
55
|
-
|
|
56
|
-
```yaml
|
|
57
|
-
name: Release
|
|
58
|
-
on:
|
|
59
|
-
push:
|
|
60
|
-
branches:
|
|
61
|
-
- master # or main
|
|
62
|
-
|
|
63
|
-
permissions:
|
|
64
|
-
contents: read # for checkout
|
|
65
|
-
|
|
66
|
-
jobs:
|
|
67
|
-
release:
|
|
68
|
-
name: Release
|
|
69
|
-
runs-on: ubuntu-latest
|
|
70
|
-
permissions:
|
|
71
|
-
contents: write # to be able to publish a GitHub release
|
|
72
|
-
issues: write # to be able to comment on released issues
|
|
73
|
-
pull-requests: write # to be able to comment on released pull requests
|
|
74
|
-
id-token: write # to enable use of OIDC for trusted publishing and npm provenance
|
|
75
|
-
steps:
|
|
76
|
-
- name: Checkout
|
|
77
|
-
uses: actions/checkout@v4
|
|
78
|
-
with:
|
|
79
|
-
fetch-depth: 0
|
|
80
|
-
- name: Setup Node.js
|
|
81
|
-
uses: actions/setup-node@v4
|
|
82
|
-
with:
|
|
83
|
-
node-version: "lts/*"
|
|
84
|
-
- name: Install dependencies
|
|
85
|
-
run: npm clean-install
|
|
86
|
-
- name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
|
|
87
|
-
run: npm audit signatures
|
|
88
|
-
- name: Release
|
|
89
|
-
env:
|
|
90
|
-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
91
|
-
run: npx semantic-release
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
## Pushing `package.json` changes to your repository
|
|
95
|
-
|
|
96
|
-
If you choose to commit changes to your `package.json` [against our recommendation](../../support/FAQ.md#making-commits-during-the-release-process-adds-significant-complexity), the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used.
|
|
97
|
-
|
|
98
|
-
**Note**: Automatically populated `GITHUB_TOKEN` cannot be used if branch protection is enabled for the target branch.
|
|
99
|
-
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.
|
|
100
|
-
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.
|
|
101
|
-
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.
|
|
102
|
-
|
|
103
|
-
If the risk is acceptable, 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:
|
|
104
|
-
|
|
105
|
-
```yaml
|
|
106
|
-
- name: Checkout
|
|
107
|
-
uses: actions/checkout@v2
|
|
108
|
-
with:
|
|
109
|
-
fetch-depth: 0
|
|
110
|
-
persist-credentials: false # <--- this
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
## Trigger semantic-release on demand
|
|
114
|
-
|
|
115
|
-
### Using GUI:
|
|
116
|
-
|
|
117
|
-
You can use [Manual Triggers](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/) for GitHub Actions.
|
|
118
|
-
|
|
119
|
-
### Using HTTP:
|
|
120
|
-
|
|
121
|
-
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.:
|
|
122
|
-
|
|
123
|
-
```yaml
|
|
124
|
-
name: Release
|
|
125
|
-
on:
|
|
126
|
-
repository_dispatch:
|
|
127
|
-
types: [semantic-release]
|
|
128
|
-
jobs:
|
|
129
|
-
# ...
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
To trigger a release, call (with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) stored in `GITHUB_TOKEN` environment variable):
|
|
133
|
-
|
|
134
|
-
```
|
|
135
|
-
$ 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" }'
|
|
136
|
-
```
|
|
@@ -1,98 +0,0 @@
|
|
|
1
|
-
# Using semantic-release with [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd)
|
|
2
|
-
|
|
3
|
-
## Environment variables
|
|
4
|
-
|
|
5
|
-
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables).
|
|
6
|
-
|
|
7
|
-
**Note**: Make sure to configure your release branch as [protected](https://docs.gitlab.com/ce/user/project/protected_branches.html) in order for the CI/CD build to access the protected variables.
|
|
8
|
-
|
|
9
|
-
## npm provenance
|
|
10
|
-
|
|
11
|
-
Since GitLab CI is a [supported provider](https://docs.npmjs.com/generating-provenance-statements#provenance-limitations) for [npm provenance](https://docs.npmjs.com/generating-provenance-statements), it is recommended to enable this to increase supply-chain security for your npm packages.
|
|
12
|
-
Find more detail about configuring npm to publish with provenance through semantic-release [in the documentation for our npm plugin](https://github.com/semantic-release/npm#npm-provenance).
|
|
13
|
-
|
|
14
|
-
## Node project configuration
|
|
15
|
-
|
|
16
|
-
GitLab CI supports [Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html) allowing to test on multiple Node versions and publishing a release only when all test pass.
|
|
17
|
-
|
|
18
|
-
**Note**: The publish pipeline must run a [Node version that meets our version requirement](../../support/node-version.md).
|
|
19
|
-
|
|
20
|
-
### `.gitlab-ci.yml` configuration for Node projects
|
|
21
|
-
|
|
22
|
-
This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with `.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
|
|
23
|
-
|
|
24
|
-
**Note**: The`semantic-release` execution command varies depending on whether you are using a [local](../../usage/installation.md#local-installation) or [global](../../usage/installation.md#global-installation) **semantic-release** installation.
|
|
25
|
-
|
|
26
|
-
```yaml
|
|
27
|
-
# The release pipeline will run only if all jobs in the test pipeline are successful
|
|
28
|
-
stages:
|
|
29
|
-
- test
|
|
30
|
-
- release
|
|
31
|
-
|
|
32
|
-
before_script:
|
|
33
|
-
- npm install
|
|
34
|
-
|
|
35
|
-
node:10:
|
|
36
|
-
image: node:10
|
|
37
|
-
stage: test
|
|
38
|
-
script:
|
|
39
|
-
- npm test
|
|
40
|
-
|
|
41
|
-
node:12:
|
|
42
|
-
image: node:12
|
|
43
|
-
stage: test
|
|
44
|
-
script:
|
|
45
|
-
- npm test
|
|
46
|
-
|
|
47
|
-
publish:
|
|
48
|
-
image: node:12
|
|
49
|
-
stage: release
|
|
50
|
-
script:
|
|
51
|
-
- npx semantic-release
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
### `.gitlab-ci.yml` configuration for all projects
|
|
55
|
-
|
|
56
|
-
This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with `.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
|
|
57
|
-
|
|
58
|
-
**Note**: 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.
|
|
59
|
-
|
|
60
|
-
```yaml
|
|
61
|
-
# The release pipeline will run only on the master/main branch a commit is triggered
|
|
62
|
-
stages:
|
|
63
|
-
- release
|
|
64
|
-
|
|
65
|
-
release:
|
|
66
|
-
image: node:10-buster-slim
|
|
67
|
-
stage: release
|
|
68
|
-
before_script:
|
|
69
|
-
- apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
|
|
70
|
-
- npm install -g semantic-release @semantic-release/gitlab
|
|
71
|
-
script:
|
|
72
|
-
- semantic-release
|
|
73
|
-
rules:
|
|
74
|
-
- if: $CI_COMMIT_BRANCH == "master" # or main
|
|
75
|
-
|
|
76
|
-
release:
|
|
77
|
-
image: node:12-buster-slim
|
|
78
|
-
stage: release
|
|
79
|
-
before_script:
|
|
80
|
-
- apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
|
|
81
|
-
- npm install -g semantic-release @semantic-release/gitlab
|
|
82
|
-
script:
|
|
83
|
-
- semantic-release
|
|
84
|
-
rules:
|
|
85
|
-
- if: $CI_COMMIT_BRANCH == "master" # or main
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
### `package.json` configuration
|
|
89
|
-
|
|
90
|
-
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
|
91
|
-
|
|
92
|
-
```json
|
|
93
|
-
{
|
|
94
|
-
"devDependencies": {
|
|
95
|
-
"semantic-release": "^15.0.0"
|
|
96
|
-
}
|
|
97
|
-
}
|
|
98
|
-
```
|
|
@@ -1,61 +0,0 @@
|
|
|
1
|
-
# Using semantic-release with [Jenkins CI](https://www.jenkins.io/doc/book/pipeline/)
|
|
2
|
-
|
|
3
|
-
## Environment variables
|
|
4
|
-
|
|
5
|
-
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/)..
|
|
6
|
-
|
|
7
|
-
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
|
|
8
|
-
|
|
9
|
-
## Node.js project configuration
|
|
10
|
-
|
|
11
|
-
### `Jenkinsfile (Declarative Pipeline)` configuration for a Node.js job
|
|
12
|
-
|
|
13
|
-
**Note**: The publish pipeline must run a Node version that [meets our requirement](../../support/node-version.md).
|
|
14
|
-
|
|
15
|
-
This example is a minimal configuration for **semantic-release** with a build running a version of Node labelled as "node LTS".
|
|
16
|
-
Since versions of Node are manually downloaded and labelled, we recommend keeping the version used for the release steps up-to-date with the latest LTS version.
|
|
17
|
-
See the [Jenkins documentation](https://www.jenkins.io/doc/) for additional configuration options.
|
|
18
|
-
|
|
19
|
-
```yaml
|
|
20
|
-
// The release stage in the pipeline will run only if the test stage in the pipeline is successful
|
|
21
|
-
pipeline {
|
|
22
|
-
agent any
|
|
23
|
-
environment {
|
|
24
|
-
GH_TOKEN = credentials('some-id')
|
|
25
|
-
}
|
|
26
|
-
stages {
|
|
27
|
-
stage('Test') {
|
|
28
|
-
steps {
|
|
29
|
-
sh '''
|
|
30
|
-
# Configure your test steps here (checkout, npm install, tests etc)
|
|
31
|
-
npm install
|
|
32
|
-
npm test
|
|
33
|
-
'''
|
|
34
|
-
}
|
|
35
|
-
}
|
|
36
|
-
stage('Release') {
|
|
37
|
-
tools {
|
|
38
|
-
nodejs "node LTS"
|
|
39
|
-
}
|
|
40
|
-
steps {
|
|
41
|
-
sh '''
|
|
42
|
-
# Run optional required steps before releasing
|
|
43
|
-
npx semantic-release
|
|
44
|
-
'''
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
}
|
|
48
|
-
}
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
### `package.json` configuration for a Node job
|
|
52
|
-
|
|
53
|
-
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
|
54
|
-
|
|
55
|
-
```json
|
|
56
|
-
{
|
|
57
|
-
"devDependencies": {
|
|
58
|
-
"semantic-release": "^18.0.0"
|
|
59
|
-
}
|
|
60
|
-
}
|
|
61
|
-
```
|
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
# Using semantic-release with [Travis CI](https://travis-ci.org)
|
|
2
|
-
|
|
3
|
-
## Environment variables
|
|
4
|
-
|
|
5
|
-
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env).
|
|
6
|
-
|
|
7
|
-
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
|
|
8
|
-
|
|
9
|
-
## Node.js projects configuration
|
|
10
|
-
|
|
11
|
-
### `.travis.yml` configuration for multiple Node.js jobs
|
|
12
|
-
|
|
13
|
-
This example is a minimal configuration for **semantic-release** with a build running Node 14 and 16. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
|
|
14
|
-
|
|
15
|
-
This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
|
|
16
|
-
|
|
17
|
-
It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
|
|
18
|
-
|
|
19
|
-
**Note**: It's not recommended to run the `semantic-release` command in the Travis `script` step as each script in this step will be executed regardless of the outcome of the previous one. See [travis-ci/travis-ci#1066](https://github.com/travis-ci/travis-ci/issues/1066).
|
|
20
|
-
|
|
21
|
-
**Advanced configuration**: Running the tests in the `script` step of the `release` stage is not necessary as the previous stage(s) already ran them. To increase speed, the `script` step of the `release` stage can be overwritten to skip the tests. Note that other commands such as build or compilation might still be required.
|
|
22
|
-
|
|
23
|
-
```yaml
|
|
24
|
-
language: node_js
|
|
25
|
-
|
|
26
|
-
node_js:
|
|
27
|
-
- 14
|
|
28
|
-
- 16
|
|
29
|
-
|
|
30
|
-
jobs:
|
|
31
|
-
include:
|
|
32
|
-
# Define the release stage that runs semantic-release
|
|
33
|
-
- stage: release
|
|
34
|
-
node_js: lts/*
|
|
35
|
-
# Advanced: optionally overwrite your default `script` step to skip the tests
|
|
36
|
-
# script: skip
|
|
37
|
-
deploy:
|
|
38
|
-
provider: script
|
|
39
|
-
skip_cleanup: true
|
|
40
|
-
script:
|
|
41
|
-
- npx semantic-release
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
### `package.json` configuration for multiple Node jobs
|
|
45
|
-
|
|
46
|
-
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
|
47
|
-
|
|
48
|
-
```json
|
|
49
|
-
{
|
|
50
|
-
"devDependencies": {
|
|
51
|
-
"semantic-release": "^18.0.0"
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
## Non-Node.js projects configuration
|
|
57
|
-
|
|
58
|
-
For projects that require to be tested with one or multiple version of a Non-JavaScript [language](https://docs.travis-ci.com/user/languages), optionally on multiple [Operating Systems](https://docs.travis-ci.com/user/multi-os).
|
|
59
|
-
|
|
60
|
-
This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration.
|
|
61
|
-
|
|
62
|
-
### `.travis.yml` configuration for non-JavaScript projects
|
|
63
|
-
|
|
64
|
-
This example is a minimal configuration for **semantic-release** with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go). See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
|
|
65
|
-
|
|
66
|
-
This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
|
|
67
|
-
|
|
68
|
-
It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
|
|
69
|
-
|
|
70
|
-
**Note**: It's not recommended to run the `semantic-release` command in the Travis `script` step as each script in this step will be executed regardless of the outcome of the previous one. See [travis-ci/travis-ci#1066](https://github.com/travis-ci/travis-ci/issues/1066).
|
|
71
|
-
|
|
72
|
-
**Advanced configuration**: Running the tests in the `script` step of the `release` stage is not necessary as the previous stage(s) already ran them. To increase speed, the `script` step of the `release` stage can be overwritten to skip the tests. Note that other commands such as build or compilation might still be required.
|
|
73
|
-
|
|
74
|
-
```yaml
|
|
75
|
-
language: go
|
|
76
|
-
|
|
77
|
-
go:
|
|
78
|
-
- 1.6
|
|
79
|
-
- 1.7
|
|
80
|
-
|
|
81
|
-
jobs:
|
|
82
|
-
include:
|
|
83
|
-
# Define the release stage that runs semantic-release
|
|
84
|
-
- stage: release
|
|
85
|
-
# Advanced: optionally overwrite your default `script` step to skip the tests
|
|
86
|
-
# script:
|
|
87
|
-
# - make
|
|
88
|
-
deploy:
|
|
89
|
-
provider: script
|
|
90
|
-
skip_cleanup: true
|
|
91
|
-
script:
|
|
92
|
-
# Use nvm to install and use the Node LTS version (nvm is installed on all Travis images)
|
|
93
|
-
- nvm install lts/*
|
|
94
|
-
- npx semantic-release
|
|
95
|
-
on:
|
|
96
|
-
all_branches: true
|
|
97
|
-
```
|
|
@@ -1,166 +0,0 @@
|
|
|
1
|
-
# Git authentication with SSH keys
|
|
2
|
-
|
|
3
|
-
When using [environment variables](../../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../../usage/configuration.md#configuration) (the format will be automatically converted as needed).
|
|
4
|
-
|
|
5
|
-
Alternatively the Git repository can be accessed via [SSH](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) by creating SSH keys, adding the public one to your Git hosted account and making the private one available on the CI environment.
|
|
6
|
-
|
|
7
|
-
**Note:** SSH keys allow to push the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated to the released version. Some plugins might also require an API token. See each plugin documentation for additional information.
|
|
8
|
-
|
|
9
|
-
## Generating the SSH keys
|
|
10
|
-
|
|
11
|
-
In your local repository root:
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
$ ssh-keygen -t rsa -b 4096 -C "<your_email>" -f git_deploy_key -N "<ssh_passphrase>"
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
`your_email` must be the email associated with your Git hosted account. `ssh_passphrase` must be a long and hard to guess string. It will be used later.
|
|
18
|
-
|
|
19
|
-
This will generate a public key in `git_deploy_key.pub` and a private key in `git_deploy_key`.
|
|
20
|
-
|
|
21
|
-
## Adding the SSH public key to the Git hosted account
|
|
22
|
-
|
|
23
|
-
Step by step instructions are provided for the following Git hosted services:
|
|
24
|
-
|
|
25
|
-
- [GitHub](#adding-the-ssh-public-key-to-github)
|
|
26
|
-
|
|
27
|
-
### Adding the SSH public key to GitHub
|
|
28
|
-
|
|
29
|
-
Open the `git_deploy_key.pub` file (public key) and copy the entire content.
|
|
30
|
-
|
|
31
|
-
In GitHub **Settings**, click on **SSH and GPG keys** in the sidebar, then on the **New SSH Key** button.
|
|
32
|
-
|
|
33
|
-
Paste the entire content of `git_deploy_key.pub` file (public key) and click the **Add SSH Key** button.
|
|
34
|
-
|
|
35
|
-
Delete the `git_deploy_key.pub` file:
|
|
36
|
-
|
|
37
|
-
```bash
|
|
38
|
-
$ rm git_deploy_key.pub
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
See [Adding a new SSH key to your GitHub account](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/) for more details.
|
|
42
|
-
|
|
43
|
-
## Adding the SSH private key to the CI environment
|
|
44
|
-
|
|
45
|
-
In order to be available on the CI environment, the SSH private key must be encrypted, committed to the Git repository and decrypted by the CI service.
|
|
46
|
-
|
|
47
|
-
Step by step instructions are provided for the following environments:
|
|
48
|
-
|
|
49
|
-
- [Travis CI](#adding-the-ssh-private-key-to-travis-ci)
|
|
50
|
-
- [Circle CI](#adding-the-ssh-private-key-to-circle-ci)
|
|
51
|
-
|
|
52
|
-
### Adding the SSH private key to Travis CI
|
|
53
|
-
|
|
54
|
-
Install the [Travis CLI](https://github.com/travis-ci/travis.rb#installation):
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
$ gem install travis
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
[Login](https://github.com/travis-ci/travis.rb#login) to Travis with the CLI:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
$ travis login
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
Add the [environment](https://github.com/travis-ci/travis.rb#env) variable `SSH_PASSPHRASE` to Travis with the value set during the [SSH keys generation](#generating-the-ssh-keys) step:
|
|
67
|
-
|
|
68
|
-
```bash
|
|
69
|
-
$ travis env set SSH_PASSPHRASE <ssh_passphrase>
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
[Encrypt](https://github.com/travis-ci/travis.rb#encrypt) the `git_deploy_key` (private key) using a symmetric encryption (AES-256), and store the secret in a secure environment variable in the Travis environment:
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
$ travis encrypt-file git_deploy_key
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
The `travis encrypt-file` will encrypt the private key into the `git_deploy_key.enc` file and output in the console the command to add to your `.travis.yml` file. It should look like `openssl aes-256-cbc -K $encrypted_KKKKKKKKKKKK_key -iv $encrypted_VVVVVVVVVVVV_iv -in git_deploy_key.enc -out git_deploy_key -d`.
|
|
79
|
-
|
|
80
|
-
Copy this command to your `.travis.yml` file in the `before_install` step. Change the output path to write the unencrypted key in `/tmp`: `-out git_deploy_key` => `/tmp/git_deploy_key`. This will avoid to commit / modify / delete the unencrypted key by mistake on the CI. Then add the commands to decrypt the ssh private key and make it available to `git`:
|
|
81
|
-
|
|
82
|
-
```yaml
|
|
83
|
-
before_install:
|
|
84
|
-
# Decrypt the git_deploy_key.enc key into /tmp/git_deploy_key
|
|
85
|
-
- openssl aes-256-cbc -K $encrypted_KKKKKKKKKKKK_key -iv $encrypted_VVVVVVVVVVVV_iv -in git_deploy_key.enc -out /tmp/git_deploy_key -d
|
|
86
|
-
# Make sure only the current user can read the private key
|
|
87
|
-
- chmod 600 /tmp/git_deploy_key
|
|
88
|
-
# Create a script to return the passphrase environment variable to ssh-add
|
|
89
|
-
- echo 'echo ${SSH_PASSPHRASE}' > /tmp/askpass && chmod +x /tmp/askpass
|
|
90
|
-
# Start the authentication agent
|
|
91
|
-
- eval "$(ssh-agent -s)"
|
|
92
|
-
# Add the key to the authentication agent
|
|
93
|
-
- DISPLAY=":0.0" SSH_ASKPASS="/tmp/askpass" setsid ssh-add /tmp/git_deploy_key </dev/null
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
See [Encrypting Files](https://docs.travis-ci.com/user/encrypting-files) for more details.
|
|
97
|
-
|
|
98
|
-
Delete the local private key as it won't be used anymore:
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
$ rm git_deploy_key
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
Commit the encrypted private key and the `.travis.yml` file to your repository:
|
|
105
|
-
|
|
106
|
-
```bash
|
|
107
|
-
$ git add git_deploy_key.enc .travis.yml
|
|
108
|
-
$ git commit -m "ci(travis): Add the encrypted private ssh key"
|
|
109
|
-
$ git push
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
### Adding the SSH private key to Circle CI
|
|
113
|
-
|
|
114
|
-
First we encrypt the `git_deploy_key` (private key) using a symmetric encryption (AES-256). Run the following `openssl` command and _make sure to note the output which we'll need later_:
|
|
115
|
-
|
|
116
|
-
```bash
|
|
117
|
-
$ openssl aes-256-cbc -e -p -in git_deploy_key -out git_deploy_key.enc -K `openssl rand -hex 32` -iv `openssl rand -hex 16`
|
|
118
|
-
salt=SSSSSSSSSSSSSSSS
|
|
119
|
-
key=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
|
|
120
|
-
iv =VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
Add the following [environment variables](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app) to Circle CI:
|
|
124
|
-
|
|
125
|
-
- `SSL_PASSPHRASE` - the value set during the [SSH keys generation](#generating-the-ssh-keys) step.
|
|
126
|
-
- `REPO_ENC_KEY` - the `key` (KKK) value from the `openssl` step above.
|
|
127
|
-
- `REPO_ENC_IV` - the `iv` (VVV) value from the `openssl` step above.
|
|
128
|
-
|
|
129
|
-
Then add to your `.circleci/config.yml` the commands to decrypt the ssh private key and make it available to `git`:
|
|
130
|
-
|
|
131
|
-
```yaml
|
|
132
|
-
version: 2
|
|
133
|
-
jobs:
|
|
134
|
-
coverage_test_publish:
|
|
135
|
-
# docker, working_dir, etc
|
|
136
|
-
steps:
|
|
137
|
-
- run:
|
|
138
|
-
# Decrypt the git_deploy_key.enc key into /tmp/git_deploy_key
|
|
139
|
-
- openssl aes-256-cbc -d -K $REPO_ENC_KEY -iv $REPO_ENC_IV -in git_deploy_key.enc -out /tmp/git_deploy_key
|
|
140
|
-
# Make sure only the current user can read the private key
|
|
141
|
-
- chmod 600 /tmp/git_deploy_key
|
|
142
|
-
# Create a script to return the passphrase environment variable to ssh-add
|
|
143
|
-
- echo 'echo ${SSL_PASSPHRASE}' > /tmp/askpass && chmod +x /tmp/askpass
|
|
144
|
-
# Start the authentication agent
|
|
145
|
-
- eval "$(ssh-agent -s)"
|
|
146
|
-
# Add the key to the authentication agent
|
|
147
|
-
- DISPLAY=":0.0" SSH_ASKPASS="/tmp/askpass" setsid ssh-add /tmp/git_deploy_key </dev/null
|
|
148
|
-
# checkout, restore_cache, run: yarn install, save_cache, etc.
|
|
149
|
-
# Run semantic-release after all the above is set.
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
The unencrypted key is written to `/tmp` to avoid to commit / modify / delete the unencrypted key by mistake on the CI environment.
|
|
153
|
-
|
|
154
|
-
Delete the local private key as it won't be used anymore:
|
|
155
|
-
|
|
156
|
-
```bash
|
|
157
|
-
$ rm git_deploy_key
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
Commit the encrypted private key and the `.circleci/config.yml` file to your repository:
|
|
161
|
-
|
|
162
|
-
```bash
|
|
163
|
-
$ git add git_deploy_key.enc .circleci/config.yml
|
|
164
|
-
$ git commit -m "ci(circle): Add the encrypted private ssh key"
|
|
165
|
-
$ git push
|
|
166
|
-
```
|