# `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.

### Cache

The cache is setup to invalidate when the `package-lock.json` changes.

### Authentication

By default, the component sets up the NPM configuration to use the `NPM_TOKEN` environment variable. This defaults to `${CI_JOB_TOKEN}`.

The `NPM_TOKEN` can be customised in cases where the `CI_JOB_TOKEN` does not have the correct permissions.

[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