Merge branch 'nfriend-add-semantic-release-example' into 'master'

Add example of publishing NPM packages using semantic-release

See merge request gitlab-org/gitlab!48701

doc/ci/examples/README.md

@@ -41,8 +41,9 @@ The following table lists examples with step-by-step tutorials that are containe
 | Ruby on Heroku                | [Test and deploy a Ruby application with GitLab CI/CD](test-and-deploy-ruby-application-to-heroku.md).                     |
 | Scala on Heroku               | [Test and deploy a Scala application to Heroku](test-scala-application.md).                                                |
 | Parallel testing Ruby & JS    | [GitLab CI/CD parallel jobs testing for Ruby & JavaScript projects](https://docs.knapsackpro.com/2019/how-to-run-parallel-jobs-for-rspec-tests-on-gitlab-ci-pipeline-and-speed-up-ruby-javascript-testing). |
-| Secrets management with Vault | [Authenticating and Reading Secrets With Hashicorp Vault](authenticating-with-hashicorp-vault/index.md).                    |
-| Multi project pipeline | [Build, test deploy using multi project pipeline](https://gitlab.com/gitlab-examples/upstream-project).                    |
+| Secrets management with Vault | [Authenticating and Reading Secrets With Hashicorp Vault](authenticating-with-hashicorp-vault/index.md).                   |
+| Multi project pipeline        | [Build, test deploy using multi project pipeline](https://gitlab.com/gitlab-examples/upstream-project).                    |
+| NPM with semantic-release     | [Publish NPM packages to the GitLab Package Registry using semantic-release](semantic-release.md).                         |
 
 ### Contributing examples
 

doc/ci/examples/semantic-release.md

+---
+stage: Package
+group: Package
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Publish NPM packages to the GitLab Package Registry using semantic-release
+
+This guide demonstrates how to automatically publish NPM packages to the [GitLab Package Registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release).
+
+You can also view or fork the complete [example source](https://gitlab.com/gitlab-examples/semantic-release-npm).
+
+## Initialize the module
+
+1. Open a terminal and navigate to the project's repo
+1. Run `npm init`. Name the module according to [the Package Registry's naming conventions](../../user/packages/npm_registry/index.md#package-naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`.
+
+1. Install the following NPM packages:
+
+   ```shell
+   npm install semantic-release @semantic-release/git @semantic-release/gitlab @semantic-release/npm --save-dev
+   ```
+
+1. Add the following properties to the module's `package.json`:
+
+   ```json
+   {
+     "scripts": {
+       "semantic-release": "semantic-release"
+     },
+     "publishConfig": {
+       "access": "public"
+     },
+     "files": [ <path(s) to files here> ]
+   }
+   ```
+
+1. Update the `files` key with glob pattern(s) that selects all files that should be included in the published module. More information about `files` can be found [in NPM's documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#files).
+
+1. Add a `.gitignore` file to the project to avoid committing `node_modules`:
+
+   ```plaintext
+   node_modules
+   ```
+
+## Configure the pipeline
+
+Create a `.gitlab-ci.yml` with the following content:
+
+```yaml
+default:
+  image: node:latest
+  before_script:
+    - npm ci --cache .npm --prefer-offline
+    - |
+      {
+        echo "@${CI_PROJECT_ROOT_NAMESPACE}:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
+        echo "${CI_API_V4_URL#https?}/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=\${CI_JOB_TOKEN}"
+      } | tee --append .npmrc
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - .npm/
+
+workflow:
+  rules:
+    - if: $CI_COMMIT_BRANCH
+
+variables:
+  NPM_TOKEN: ${CI_JOB_TOKEN}
+
+stages:
+  - release
+
+publish:
+  stage: release
+  script:
+    - npm run semantic-release
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+This example configures the pipeline with a single job, `publish`, which runs `semantic-release`. The semantic-release library publishes new versions of the NPM package and creates new GitLab releases (if necessary).
+
+The default `before_script` generates a temporary `.npmrc` that is used to authenticate to the Package Registry during the `publish` job.
+
+## Set up environment variables
+
+As part of publishing a package, semantic-release increases the version number in `package.json`. For semantic-release to commit this change and push it back to GitLab, the pipeline requires a custom environment variable named `GITLAB_TOKEN`. To create this variable:
+
+1. Navigate to **Project > Settings > Access Tokens**.
+1. Give the token a name, and select the `api` scope.
+1. Click **Create project access token** and copy its value.
+1. Navigate to **Project > Settings > CI / CD > Variables**.
+1. Click **Add Variable**.
+1. In the **Key** field, enter `GITLAB_TOKEN`. In the **Value** field, paste the token created above. Check the **Mask variable** option and click **Add variable**.
+
+## Configure semantic-release
+
+semantic-release pulls its configuration info from a `.releaserc.json` file in the project. Create a `.releaserc.json` at the root of the repository:
+
+```json
+{
+  "branches": ["master"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/gitlab",
+    "@semantic-release/npm",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ]
+  ]
+}
+```
+
+## Begin publishing releases
+
+Test the pipeline by creating a commit with a message like:
+
+```plaintext
+fix: testing patch releases
+```
+
+Push the commit to `master`. The pipeline should create a new release (`v1.0.0`) on the project's **Releases** page and publish a new version of the package to the project's **Package Registry** page.
+
+To create a minor release, use a commit message like:
+
+```plaintext
+feat: testing minor releases
+```
+
+Or, for a breaking change:
+
+```plaintext
+feat: testing major releases
+
+BREAKING CHANGE: This is a breaking change.
+```
+
+More information about how commit messages are mapped to releases can be found in [semantic-releases's documentation](https://github.com/semantic-release/semantic-release#how-does-it-work).
+
+## Use the module in a project
+
+To use the published module, add an `.npmrc` file to the project that depends on the module. For example, to use [the example project](https://gitlab.com/gitlab-examples/semantic-release-npm)'s module:
+
+```plaintext
+@gitlab-examples:registry=https://gitlab.com/api/v4/packages/npm/
+```
+
+Then, install the module:
+
+```shell
+npm install --save @gitlab-examples/semantic-release-npm
+```

doc/user/packages/npm_registry/index.md

@@ -277,6 +277,10 @@ deploy:
     - npm publish
 ```
 
+See the
+[Publish NPM packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md)
+step-by-step guide and demo project for a complete example.
+
 ## Publishing packages with the same name or version
 
 You cannot publish a package if a package of the same name and version already exists.