docs: update some stale links to GitLab docs, plus a few minor spelling fixes

# GitLab CI template for {{cookiecutter.template_name}}

{% if cookiecutter.template_type == 'build' %}

This project implements a GitLab CI/CD template to build, test and analyse your [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}) projects.

This project implements a GitLab CI/CD template to build, test, and analyse your [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}) projects.

## Usage

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component-in-a-cicd-configuration) 

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.

### Use as a CI/CD component

```properties

# see: https://docs.sonarqube.org/latest/analysis/languages/{{cookiecutter.project_slug}}/

# set your source directory(ies) here (relative to the sonar-project.properties file)

# set your source directories here (relative to the sonar-project.properties file)

sonar.sources=.

# exclude unwanted directories and files from being analysed

sonar.exclusions=output/**,**/*_test.{{cookiecutter.template_prefix}}

# set your tests directory(ies) here (relative to the sonar-project.properties file)

# set your tests directories here (relative to the sonar-project.properties file)

sonar.tests=.

sonar.test.inclusions=**/*_test.{{cookiecutter.template_prefix}}

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

| `publish-enabled` / `{{cookiecutter.template_PREFIX}}_PUBLISH_ENABLED` | Variable to enable the publish job     | _none_ (disabled) |

| `publish-args` / `{{cookiecutter.template_PREFIX}}_PUBLISH_ARGS`    | Arguments used by the publish job      | `publish --with-default-args` |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_LOGIN` | Login to use to publish           | **has to be defined** |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_PASSWORD` | Password to use to publish     | **has to be defined** |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_LOGIN` | Login to use to publish           | **must be defined** |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_PASSWORD` | Password to use to publish     | **must be defined** |

### Secrets management

Here are some advices about your **secrets** (variables marked with a :lock:):

1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui):

    * [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-custom-variable) to prevent them from being inadvertently

1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#define-a-cicd-variable-in-the-ui):

    * [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently

      displayed in your job logs,

    * [**protected**](https://docs.gitlab.com/ee/ci/variables/#protect-a-custom-variable) if you want to secure some secrets

    * [**protected**](https://docs.gitlab.com/ee/ci/variables/#protect-a-cicd-variable) if you want to secure some secrets

      you don't want everyone in the project to have access to (for instance production secrets).

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#masked-variable-requirements), 

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable), 

  simply define its value as the [Base64](https://en.wikipedia.org/wiki/Base64) encoded value prefixed with `@b64@`:

  it will then be possible to mask it and the template will automatically decode it prior to using it.

3. Don't forget to escape special characters (ex: `$` -> `$$`).

3. Don't forget to escape special characters (e.g.: `$` -> `$$`).

{%- elif cookiecutter.template_type == 'deploy' %}

This project implements a GitLab CI/CD template to deploy your application to [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}).

## Usage

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component-in-a-cicd-configuration) 

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.

### Use as a CI/CD component

## Understand

This chapter introduces key notions and principle to understand how this template works.

This chapter introduces key notions and principles to understand how this template works.

### Managed deployment environments

### Deployment context variables

In order to manage the various deployment environments, this template provides a couple of **dynamic variables**

that you might use in your hook scripts, deployment manifests and other deployment resources:

that you might use in your hook scripts, deployment manifests, and other deployment resources:

* `${environment_type}`: the current deployment environment type (`review`, `integration`, `staging` or `production`)

* `${environment_name}`: a generated application name to use for the current deployment environment (ex: `myapp-review-fix-bug-12` or `myapp-staging`) - _details below_

* `${environment_name}`: a generated application name to use for the current deployment environment (e.g.: `myapp-review-fix-bug-12` or `myapp-staging`) - _details below_

#### Generated environment name

> TODO: explain here the supported techniques to deploy and cleanup the environments.

>

> You should also explained clearly what is expected from the template user and what is the lookup policy in case the template

> You should also explain clearly what is expected from the template user and what is the lookup policy in case the template

> implements one.

>

> Example:

3. if not found: the cleanup job will fail.

> :information_source: Your deployment (and cleanup) scripts have to be able to cope with various environments, each with different application names, exposed routes, settings, ...

> Part of this complexity can be handled by the lookup policies described above (ex: one script per env) and also by using available environment variables:

> Part of this complexity can be handled by the lookup policies described above (e.g.: one script per env) and also by using available environment variables:

>

> 1. [deployment context variables](#deployment-context-variables) provided by the template:

>     * `${environment_type}`: the current environment type (`review`, `integration`, `staging` or `production`)

>     * `${environment_name}`: the application name to use for the current environment (ex: `myproject-review-fix-bug-12` or `myproject-staging`)

>     * `${environment_name}`: the application name to use for the current environment (e.g.: `myproject-review-fix-bug-12` or `myproject-staging`)

>     * `${hostname}`: the environment hostname, extracted from the current environment url (after late variable expansion - see below)

> 2. any [GitLab CI variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)

> 3. any [custom variable](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project)

>     (ex: `${SECRET_TOKEN}` that you have set in your project CI/CD variables)

> 3. any [custom variable](https://docs.gitlab.com/ee/ci/variables/#for-a-project)

>     (e.g.: `${SECRET_TOKEN}` that you have set in your project CI/CD variables)

### Environments URL management

The {{cookiecutter.template_name}} template supports two ways of providing your environments url:

* a **static way**: when the environments url can be determined in advance, probably because you're exposing your routes through a DNS you manage,

* a [**dynamic way**](https://docs.gitlab.com/ee/ci/environments/#set-dynamic-environment-urls-after-a-job-finishes): when the url cannot be known before the

* a [**dynamic way**](https://docs.gitlab.com/ee/ci/environments/#set-a-dynamic-environment-url): when the url cannot be known before the

  deployment job is executed.

The **static way** can be implemented simply by setting the appropriate configuration variable(s) depending on the environment (see environments configuration chapters):

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable), 

  simply define its value as the [Base64](https://en.wikipedia.org/wiki/Base64) encoded value prefixed with `@b64@`: 

  it will then be possible to mask it and the template will automatically decode it prior to using it.

3. Don't forget to escape special characters (ex: `$` -> `$$`).

3. Don't forget to escape special characters (e.g.: `$` -> `$$`).

### Global configuration

| `base-app-name` / `{{cookiecutter.template_PREFIX}}_BASE_APP_NAME`      | Base application name                  | `$CI_PROJECT_NAME` ([see GitLab doc](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)) |

| `api-url` / `{{cookiecutter.template_PREFIX}}_API_URL`            | Default {{cookiecutter.template_name}} API url | _none_ |

| :lock: `{{cookiecutter.template_PREFIX}}_API_TOKEN`          | Default {{cookiecutter.template_name}} API token | _none_ |

| `environment-url` / `{{cookiecutter.template_PREFIX}}_ENVIRONMENT_URL`    | Default environments url _(only define for static environment URLs declaration)_<br/>_supports late variable expansion (ex: `https://%{environment_name}.{{cookiecutter.project_slug}}.acme.com`)_ | _none_ |

| `environment-url` / `{{cookiecutter.template_PREFIX}}_ENVIRONMENT_URL`    | Default environments url _(only define for static environment URLs declaration)_<br/>_supports late variable expansion (e.g.: `https://%{environment_name}.{{cookiecutter.project_slug}}.acme.com`)_ | _none_ |

| `scripts-dir` / `{{cookiecutter.template_PREFIX}}_SCRIPTS_DIR`        | Directory where deploy & cleanup scripts are located | `.` _(root project dir)_ |

### Review environments configuration

| Input / Variable         | Description                            | Default value     |

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

| `review-project` / `{{cookiecutter.template_PREFIX}}_REVIEW_PROJECT`     | Project ID for `review` env | _none_ (disabled) |

| `review-app-name` / `{{cookiecutter.template_PREFIX}}_REVIEW_APP_NAME`    | Application name for `review` env      | `"{{ '${' }}{{cookiecutter.template_PREFIX}}_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}"` (ex: `myproject-review-fix-bug-12`) |

| `review-app-name` / `{{cookiecutter.template_PREFIX}}_REVIEW_APP_NAME`    | Application name for `review` env      | `"{{ '${' }}{{cookiecutter.template_PREFIX}}_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}"` (e.g.: `myproject-review-fix-bug-12`) |

| `review-api-url` / `{{cookiecutter.template_PREFIX}}_REVIEW_API_URL`     | API url for `review` env _(only define to override default)_ | `${{cookiecutter.template_PREFIX}}_API_URL` |

| :lock: `{{cookiecutter.template_PREFIX}}_REVIEW_API_TOKEN`   | API token for `review` env _(only define to override default)_ | `${{cookiecutter.template_PREFIX}}_API_TOKEN` |

| `review-environment-url` / `{{cookiecutter.template_PREFIX}}_REVIEW_ENVIRONMENT_URL`| The review environments url _(only define for static environment URLs declaration and if different from default)_ | `${{cookiecutter.template_PREFIX}}_ENVIRONMENT_URL` |

This project implements a GitLab CI/CD template to run your automated tests with [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}).

## Usage

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component-in-a-cicd-configuration) 

**component: $CI_SERVER_FQDN**

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.

### Use as a CI/CD component