# `semantic-release`

> A job to run [semantic-release][semantic-release], a automated release deployment tool

## Overview

The `semantic-release` component automates the entire package release workflow, including determining the next version number, generating release notes, and publishing the package.

It strictly follows the [Semantic Versioning] specification and communicates the impact of changes to consumers.

## Getting Started

Include the following in `.gitlab-ci.yml`:

```yaml
include:
  - component: "${CI_SERVER_HOST}/ci/component/semantic-release@<version>"

semantic-release:
  extends: .semantic-release
```

## Usage

### Configuration

`semantic-release` [configuration] expects both instructions of which _branches_ to run on and the _plugins_ to execute.
Often this is easily represented in a [.releaserc.yml][releaserc] file. The plugins will depend on the type of project
to deploy; `semantic-release` has many open-source [plugins][plugins] that implement the common deployment steps.

`npm install --package-lock-only` will need to be ran locally to generate the `package-lock.json` file for the installed tools.

### Recipes

#### NPM

When using the `@semantic-release/npm` plugin, publishing to GitLab Package Registry can be configured with the NPM
configuration:

```yaml
semantic-release:
  extends: .semantic-release
  variables:
    NPM_TOKEN: "${CI_JOB_TOKEN}"
  before_script:
    - npm config set -- "@${CI_PROJECT_ROOT_NAMESPACE}:registry"
      "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
    - npm config set -- "${CI_API_V4_URL#https?}/packages/npm/:_authToken" '\${NPM_JOB_TOKEN}'
```

[Semantic Versioning]: https://semver.org
[semantic-release]: https://github.com/semantic-release/semantic-release
[plugins]: https://github.com/semantic-release
[configuration]: https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration
[conventional-commits]: https://www.conventionalcommits.org/
[semantic-versioning]: http://semver.org/
[oci]: oci.md
[releaserc]: ../.releaserc.yaml
[image]: https://docs.gitlab.com/ee/ci/yaml/#image