docs: update GitLab links

## Checklist

* General:

    * [ ] use [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ee/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ee/ci/caching/) configuration (wherever applicable)

    * [ ] use [rules](https://docs.gitlab.com/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ci/caching/) configuration (wherever applicable)

* Publicly usable:

    * [ ] untagged runners

    * [ ] no proxy configuration but support `http_proxy`/`https_proxy`/`no_proxy`

1. Create an issue describing the bug or enhancement you want to propose (select the right issue template).

2. Make sure the issue has been reviewed and agreed.

3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) documentation).

3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/user/project/repository/forking_workflow/) documentation).

   Don't hesitate to mark your MR as `Draft` as long as you think it's not ready to be reviewed.

### Git Commit Conventions

It can be configured with the following variables:

* `GITLAB_TOKEN`: a [group access token](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html) with at least scopes `api,read_repository`

* `GITLAB_TOKEN`: a [group access token](https://docs.gitlab.com/user/group/settings/group_access_tokens/) with at least scopes `api,read_repository`

  and `Developer` role,

* `KICKER_RESOURCE_GROUPS`: JSON configuration of GitLab groups to crawl.

Some explanations:

* `path` is a path to a [GitLab group](https://docs.gitlab.com/ee/user/group/)

  with [GitLab projects](https://docs.gitlab.com/ee/user/project/) containing Kicker resources.

* `path` is a path to a [GitLab group](https://docs.gitlab.com/user/group/)

  with [GitLab projects](https://docs.gitlab.com/user/project/) containing Kicker resources.

* `visibility` is the group/projects visibility to crawl.

* `exclude` (optional) allows to exclude some project(s) from processing.

* `extension` (optional) allows to associate Kicker resources with a separate extension (actionable within Kicker).

Examples:

- The Docker template uses [GitLab's container registry](https://docs.gitlab.com/ee/user/packages/container_registry/) by default, although any other container registry can be used by configuration.

- The Python template uses [GitLab's PyPI registry](https://docs.gitlab.com/ee/user/packages/pypi_repository/) by default, although any other PyPI registry can be used by configuration.

- The Maven template can't use [GitLab's Maven registry](https://docs.gitlab.com/ee/user/packages/maven_repository/) by default, but documents what has to be done in its `README.md`.

- The Docker template uses [GitLab's container registry](https://docs.gitlab.com/user/packages/container_registry/) by default, although any other container registry can be used by configuration.

- The Python template uses [GitLab's PyPI registry](https://docs.gitlab.com/user/packages/pypi_repository/) by default, although any other PyPI registry can be used by configuration.

- The Maven template can't use [GitLab's Maven registry](https://docs.gitlab.com/user/packages/maven_repository/) by default, but documents what has to be done in its `README.md`.

## The right template perimeter

## No nested includes

[Nested includes](https://docs.gitlab.com/ee/ci/yaml/includes.html#use-nested-includes) shall not be used in _to be continuous_ templates for the following reasons:

[Nested includes](https://docs.gitlab.com/ci/yaml/includes/#use-nested-includes) shall not be used in _to be continuous_ templates for the following reasons:

- it would prevent _to be continuous_ templates from being [remote included](https://docs.gitlab.com/ee/ci/yaml/#includeremote) (b.t.w. this is the technique used by [R2Devops](https://r2devops.io/), also featuring _to be continuous_ templates)

- it would prevent _to be continuous_ templates from being [remote included](https://docs.gitlab.com/ci/yaml/#includeremote) (b.t.w. this is the technique used by [R2Devops](https://r2devops.io/), also featuring _to be continuous_ templates)

- it would prevent _to be continuous_ templates from being included from another root path than `/to-be-continuous` (it may happen in some organizations when the groups hierarchy is locked by governance rules)

- should the nested includes be versioned or not? both options have serious drawback (dependency hell vs. non-deterministic)

| Environment Type | Description                                       | Associated branch(es)                  |

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

| **Review**       | Those are dynamic and ephemeral environments to deploy your ongoing developments.<br/> It is a strict equivalent of GitLab's [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/) feature. | All **development branches** (non-integration, non-production) |

| **Review**       | Those are dynamic and ephemeral environments to deploy your ongoing developments.<br/> It is a strict equivalent of GitLab's [Review Apps](https://docs.gitlab.com/ci/review_apps/) feature. | All **development branches** (non-integration, non-production) |

| **Integration**  | A single environment to continuously deploy your integration branch. | The **integration branch** (`develop` by default) |

| **Staging**      | A single environment to continuously deploy your production branch.<br/> It is an iso-prod environment, meant for running the automated acceptance tests prior to deploying to the production env. | The **production branch** (`main` or `master`  by default) |

| **Production**   | _Well.. the prod!_ | The **production branch** (`main` or `master`  by default) |

We decided that those tools:

- must **always** produce the textual (human readable) report in the console,

- when available, they must produce the [GitLab-supported format report](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html)

- when available, they must produce the [GitLab-supported format report](https://docs.gitlab.com/ci/yaml/artifacts_reports/)

- when SonarQube template is detected (by the presence of `$SONAR_HOST_URL` variable) and when available, they shall produce the SonarQube-supported format report ([test execution report](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/overview/#test-execution-reports), [coverage report](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/overview/#coverage-support) and [external analyzer reports](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/importing-external-issues/external-analyzer-reports/))

- when DefectDojo template is detected (by the presence of the corresponding `$DEFECTDOJO_XXX_REPORTS` variable) and when available, they shall produce the [DefectDojo-supported format report](https://defectdojo.github.io/django-DefectDojo/integrations/parsers/file/)

Those output can be artifacts (ex: result of a build), reports (ex: SAST tools reports consumed by the SonarQube template or DefectDojo), and sometimes

it could be a dynamic variable.

For this last need, _to be continuous_ uses the [dotenv report format](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsdotenv) to propagate output environment variables downstream.

For this last need, _to be continuous_ uses the [dotenv report format](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsdotenv) to propagate output environment variables downstream.

Examples:

In that case, _to be continuous_ templates shall observe a _reasonable_ rollout time before implementing

them, not to break projects using them on a self-managed server.

For security patches, GitLab [maintains the two previous `major.minor` versions](https://docs.gitlab.com/ee/policy/maintenance.html).

For security patches, GitLab [maintains the two previous `major.minor` versions](https://docs.gitlab.com/policy/maintenance/).

We decided to observe the same delay before implementing a non-backward compatible feature.

I.e. wait that the GitLab version that introduced the feature is the oldest version maintained by GitLab.

## Job prototype

Every template shall define a ([hidden](https://docs.gitlab.com/ee/ci/yaml/#hide-jobs))

base job with name `.<prefix>-base`, [extended](https://docs.gitlab.com/ee/ci/yaml/#extends) by all other jobs,

Every template shall define a ([hidden](https://docs.gitlab.com/ci/yaml/#hide-jobs))

base job with name `.<prefix>-base`, [extended](https://docs.gitlab.com/ci/yaml/#extends) by all other jobs,

that defines:

* the default image to use (variabilized)

* a **build** job (mandatory) mapped on the `build` stage that builds the code (if applicable for the language) and runs the unit tests.<br/>

  Unit Tests should support the following GitLab CI features:

    * unit tests report integration using [JUnit test report](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsjunit)

    * code coverage computing and [integration](https://docs.gitlab.com/ee/ci/yaml/#coverage)

    * unit tests report integration using [JUnit test report](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsjunit)

    * code coverage computing and [integration](https://docs.gitlab.com/ci/yaml/#coverage)

* any number of **code analysis** jobs (optional) mapped on the `test` stage that allow triggering language specific code analysis tools

  ([SAST](https://en.wikipedia.org/wiki/Static_program_analysis), dependency check, ...)

    * if those jobs are time consuming they shall be [triggered manually](https://docs.gitlab.com/ee/ci/yaml/#whenmanual)

    * if those jobs are time consuming they shall be [triggered manually](https://docs.gitlab.com/ci/yaml/#whenmanual)

    * they shall be enabled/disabled by configuration (ex: a job is disabled by default and is enabled when the `SOMEJOB_ENABLED` variable is set)

    * whenever possible, code analysis on non-master branches should be a partial code analysis (only on changes in the branch)

* a **publish** job (optional) mapped on the `publish` stage that can be [triggered manually](https://docs.gitlab.com/ee/ci/yaml/#whenmanual)

* a **publish** job (optional) mapped on the `publish` stage that can be [triggered manually](https://docs.gitlab.com/ci/yaml/#whenmanual)

  to perform a publish of the built artifacts on a package repository (ex: Artifactory, NPM or Maven repository)

### Code Analysis templates

They shall implement one or several code analysis jobs mapped on the `test` stage that allow triggering code analysis

* if those jobs are time consuming they shall be [triggered manually](https://docs.gitlab.com/ee/ci/yaml/#whenmanual)

* if those jobs are time consuming they shall be [triggered manually](https://docs.gitlab.com/ci/yaml/#whenmanual)

* they shall be enabled/disabled by configuration (ex: a job is disabled by default and is enabled when the `SOMEJOB_ENABLED` variable is set)

* whenever possible, code analysis on non-master branches should be a partial code analysis (only on changes in the branch)

* one generic hidden **deployment** job (mandatory), in charge of deploying the code to some parameterized environment

    * must be enabled/disabled by configuration

    * must use the [`resource_group`](https://docs.gitlab.com/ee/ci/yaml/#resource_group) feature to prevent multiple

    * must use the [`resource_group`](https://docs.gitlab.com/ci/yaml/#resource_group) feature to prevent multiple

      pipelines deploying to the same environment at the same time

    * must propagate the `$CI_ENVIRONMENT_URL` variable as a `environment_url.txt` artifact file (legacy way)

    * must propagate deployed environment information as [dotenv artifacts](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsdotenv) (the _dotenv_ way):

    * must propagate deployed environment information as [dotenv artifacts](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsdotenv) (the _dotenv_ way):

        * `environment_type`: the type of environment (`review`, `integration`, `staging` or `production`),

        * `environment_name`: the application name,

        * `environment_url`: set to `$CI_ENVIRONMENT_URL`.

    * extends the generic deployment job

    * mapped on the `deploy` stage

    * must be executed on non-`master`, non-`develop` branches only

    * must reference the **cleanup-review** job (see below) in its [`environment:on_stop`](https://docs.gitlab.com/ee/ci/yaml/#environmenton_stop) event

    * must reference the **cleanup-review** job (see below) in its [`environment:on_stop`](https://docs.gitlab.com/ci/yaml/#environmenton_stop) event

* one **cleanup-review** job (mandatory) in charge of deleting the corresponding dynamic review environment

    * extends the generic cleanup job

    * mapped on the `deploy` stage

    * must be executed on non-`master` branches only

    * must be associated to the [`environment:action:stop`](https://docs.gitlab.com/ee/ci/yaml/#environmentaction) event

    * must be associated to the [`environment:action:stop`](https://docs.gitlab.com/ci/yaml/#environmentaction) event

* one **integration** job (mandatory) in charge of deploying the code on the integration environment

    * extends the generic deployment job

    * mapped on the `deploy` stage

Those jobs should implement the following features:

* tests report integration using [JUnit test report](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsjunit)

* tests report integration using [JUnit test report](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsjunit)

* auto-evaluating the environment url to test based on the presence of `$environment_url` (possibly propagated by an upstream deployment template

using [dotenv artifacts](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsdotenv)) or a `environment_url.txt` file.

using [dotenv artifacts](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsdotenv)) or a `environment_url.txt` file.