Merge branch '408-new-job-semantic-release' into 'latest'

## Objective

Using this job, you will have benefits of using 

[`semantic-release`](https://github.com/semantic-release/semantic-release){:target="_blank"}

with your own configuration. 

**Semantic release** automates your whole versioning & package delivery. Knowing from which version number is needed and 

generating GitLab releases to publishing your package. It removes the headache you can have determining which

version of the software is needed, and the content of your release note. Learn more on the 

[official documentation](https://semantic-release.gitbook.io/semantic-release/){:target="_blank"}.

## How to use it

!!! info

    [Configuration file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file){:target="_blank"}

    can be written through different format, be sure to use a valid one (e.o. in `package.json` or `.releaserc`).

1. Have a valid `semantic-release` configuration in your repository, and update `SEMANTIC_CONFIG_DIR` with its path

1. *Optional*: If you are using [`@semantic-release/gitlab`](https://github.com/semantic-release/gitlab#environment-variables){:target="_blank"}, 

   add a [CI/CD variable](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project){:target="_blank"}

   named `GITLAB_TOKEN` containing a GitLab 

   [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html){:target="_blank"}.

1. *Optional*: If you are using a plugin which is not listed in 

   [official plugins](https://github.com/semantic-release/semantic-release/blob/master/docs/extending/plugins-list.md#plugins-list){:target="_blank"}, 

   update `SEMANTIC_ADDITIONAL_PACKAGES` with the plugins you need.

1. Add this job URL inside the `include` list of your `.gitlab-ci.yml` file (see the [quick setup](/use-the-hub/#quick-setup)). You can specify [a fixed version](#changelog) instead of `latest`.

    ```yaml

      - remote: 'https://jobs.r2devops.io/latest/semantic_release.yml'

    ```

1. If you need to customize the job (stage, variables, ...) 👉 check the [jobs

   customization](/use-the-hub/#jobs-customization)

1. Well done, your job is ready to work ! 😀

## Job details

* Job name: `semantic_release`

* Docker image: [`node:16.2`](https://hub.docker.com/r/_/node){:target="_blank"}

* Default stage: `release`

* When: `${CI_COMMIT_BRANCH} == ${CI_DEFAULT_BRANCH}`

### Variables

!!! info

    You can run this job in `dry run` mode, so you don't pollute your repository with testing

    tags & releases. All you have to do is setting `SEMANTIC_DRY_RUN` as `true`, and put it right

    back to `false` as soon as you are ready to release 🎉

| Name | Description | Default |

| ---- | ----------- | ------- |

| `SEMANTIC_CONFIG_DIR` | Direction where `semantic-release` config is available | `/` | 

| `SEMANTIC_DRY_RUN` | Run the tool in [dry run](https://en.wikipedia.org/wiki/Dry_run_(testing)){:target="_blank"} |

| `SEMANTIC_RELEASE_OPTIONS` | Additional options to run on `semantic-release` command | ` ` |

| `SEMANTIC_ADDITIONAL_PACKAGES` | Additional packages to install needed to match your config (this job already installs all [official plugins](https://github.com/semantic-release/semantic-release/blob/master/docs/extending/plugins-list.md#plugins-list){:target="_blank"}) | ` ` | 

| `SEMANTIC_RELEASE_VERSION` | `semantic-release` version | `17.4.3` |

| `SEMANTIC_GITLAB_VERSION` | `@semantic-release/gitlab` version | `6.1.0` |

| `SEMANTIC_GIT_VERSION` | `@semantic-release/git` version | `9.0.0` | 

| `SEMANTIC_CHANGELOG_VERSION` | `@semantic-release/changelog` version | `5.0.1` | 

| `SEMANTIC_EXEC_VERSION` | `@semantic-release/exec` version | `5.0.0` |

| `SEMANTIC_APM_VERSION` | `@semantic-release/apm` version | `3.0.0`

### Cache

This job has the perk to use [cache](https://docs.gitlab.com/ee/ci/caching/){:target="_blank"}, 

it will be named as `${CI_COMMIT_REF_SLUG}-semantic-release`

and will cache `node_modules` generated by installation of `semantic-release` packages. So this

job will always try to be as fast as possible! 🚀

### Artifacts

This job will expose an artifact will the result from `semantic-release` and is exposed as `semantic-release logs`, 

it is also available directly in the job's logs.

name: semantic_release

description: Get your versioning & release deployments automated using semantic-release

default_stage: release

icon: 🧾

maintainer: moha-s

license: Apache-2.0

images:

  node:16.2

labels:

  - GitLab

  - Release

  - Utilities

tools:

  semantic-release: "17.4.3"

# Job from R2Devops hub --> r2devops.io

stages:

  - release

semantic_release:

  image: node:16.2

  stage: release

  variables:

    SEMANTIC_CONFIG_DIR: "/"

    SEMANTIC_DRY_RUN: "false"

    SEMANTIC_RELEASE_VERSION: "17.4.3"

    SEMANTIC_GITLAB_VERSION: "6.1.0"

    SEMANTIC_GIT_VERSION: "9.0.0"

    SEMANTIC_CHANGELOG_VERSION: "5.0.1"

    SEMANTIC_EXEC_VERSION: "5.0.0"

    SEMANTIC_APM_VERSION: "3.0.0"

    SEMANTIC_RELEASE_OPTIONS: ""

    SEMANTIC_ADDITIONAL_PACKAGES: ""

  script:

    - if [ ! -d ${CI_PROJECT_DIR}/${SEMANTIC_CONFIG_DIR} ]; then

    -   echo '${SEMANTIC_CONFIG_DIR} leads to an invalid directory'

    -   exit 1

    - fi

    - cd ${CI_PROJECT_DIR}/${SEMANTIC_CONFIG_DIR}

    # We install all official packages, so we support the wildest range of users

    - |

      npm install --save-dev semantic-release@${SEMANTIC_RELEASE_VERSION} \

      @semantic-release/gitlab@${SEMANTIC_GITLAB_VERSION} \

      @semantic-release/git@${SEMANTIC_GIT_VERSION} \

      @semantic-release/changelog@${SEMANTIC_CHANGELOG_VERSION} \

      @semantic-release/exec@${SEMANTIC_EXEC_VERSION} \

      @semantic-release/apm@${SEMANTIC_APM_VERSION}

    - if [ ! -z ${SEMANTIC_ADDITIONAL_PACKAGES} ]; then

    -   npm install --save-dev ${SEMANTIC_ADDITIONAL_PACKAGES}

    - fi

    - if [ "$SEMANTIC_RELEASE_OPTIONS" = "true" ]; then

    -   export SEMANTIC_RELEASE_OPTIONS="-d $SEMANTIC_RELEASE_OPTIONS"

    - fi

    - npx semantic-release $SEMANTIC_RELEASE_OPTIONS | tee -a output.log

  rules:

    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

      when: always

  cache:

    key: "${CI_COMMIT_REF_SLUG}-semantic-release"

    paths:

      - ${CI_PROJECT_DIR}/${SEMANTIC_CONFIG_DIR}/node_modules/

  artifacts:

    when: always

    expose_as: "semantic-release logs"

    paths:

      - output.log

* Initial version

 No newline at end of file