doc: global changes

      # Cache downloaded dependencies and plugins between builds.

      # To keep cache across branches add 'key: "$CI_JOB_NAME"'

      cache:

        key: "$CI_BUILD_REF_NAME"

        key: "$CI_COMMIT_REF_SLUG-xxx"

        paths:

          - binaries/

    ```

      # Cache downloaded dependencies and plugins between builds.

      # To keep cache across branches add 'key: "$CI_JOB_NAME"'

      cache:

        key: "$CI_BUILD_REF_NAME"

        key: "$CI_COMMIT_REF_SLUG-xxx"

        paths:

          - binaries/

</tr>

</tbody>

</table>

## Docker Images Versions

_to be continuous_ templates use - whenever possible - required tools as Docker images.

And when available, the _latest_ image version is used.

In some cases, using the latest version is a good thing, and in some other cases, the latest version is bad.

* _latest_ is **good** for:

    * DevSecOps tools (Code Quality, Security Analysis, Dependency Check, Linters ...) as using the latest version of the tool is the best way to ensure

      you're likely to detect vulnerabilities as soon as possible (well, as soon as new vulnerabilities are known and covered by DevSecOps tools).

    * Public cloud CLI clients as there is only one version of the public cloud, and the official Docker image is likely to evolve at the same time as the APIs.

* _latest_ is **not good** for:

    * Build tools as your project is developped using one specific version of the language / the build tool, and you would like to control when you change version.

    * Infrastructure-as-Code tools for the same reason as above.

    * Acceptance tests tools as the same reason as build tools.

    * Private cloud CLI clients as you may not have installed the latest version of - say - OpenShift or Kubernetes, and you'll need to use the client CLI version that matches your servers version.

!!! Success "To summarize"

    1. Make sure you explicitely override the Docker image versions of your build, Infrastructure-as-Code, private cloud CLI clients and acceptance tests tools matching your project requirements.

    2. Be aware that sometimes your pipeline may fail (without any change from you) due to a new version of DevSecOps tool that either highlights a new vulnerability (:tada:), or due to a bug or breaking change in the tool (:poop: happens).

include:

  - project: 'to-be-continuous/maven' # this is the template project

    file: '/templates/gitlab-ci-maven.yml' # template file within the project

    ref: '1.0.0' # template version

    ref: '1.0.0' # template exact version

  - project: 'to-be-continuous/aws'

    file: '/templates/gitlab-ci-aws.yml'

    ref: '1.2' # use minor version alias (uses the latest available patch version)

```

Our templates are **versioned**:

Our templates are **versioned** (compliant with [Semantic Versioning](https://semver.org/)):

* each version is exposed through a Git tag such as `0.1.0`, `1.1.2`, ...

* our recommendation is to **use a fixed version** of each template, and upgrade when a new valuable feature is rolled out.

* each version is exposed through a Git tag such as `1.1.0`, `2.1.4`, ...

* for convenience purpose, our templates also maintain a **minor version alias** tag (ex: `2.1`), always referencing the latest patched version within that minor version, 

  and also a **major version alias** tag (ex: `2`), always referencing the latest minor version within that major version.

* our recommendation is to **use a fixed version** of each template (either exact, minor or major), and upgrade when a new valuable feature is rolled out.

* you may also chose to use the **latest released** version (discouraged as a new version with breaking changes would break your pipeline).

  For this, simply include the template from `master`.

You'll find configuration details in each template reference documentation.

### How can I activate debug logs in to be continuous pipeline jobs

## Debugging _to be continuous_ jobs

Each template enable debug logs when `$TRACE` is set.

Each template enable debug logs when `$TRACE` is set to `true`.

So you may simply manually run your pipeline, and set `TRACE=true` interactively (any non-empty value is okay).

So you may simply manually run your pipeline, and set `TRACE=true` interactively.

:warning: this is different (and complementary) to GitLab's [`CI_DEBUG_TRACE`](https://docs.gitlab.com/ee/ci/variables/#enable-debug-logging) variable.

## Docker Images Versions

_to be continuous_ templates use - whenever possible - required tools as Docker images.

And when available, the _latest_ image version is used.

In some cases, using the latest version is a good thing, and in some other cases, the latest version is bad.

* _latest_ is **good** for:

    * DevSecOps tools (Code Quality, Security Analysis, Dependency Check, Linters ...) as using the latest version of the tool is the best way to ensure

      you're likely to detect vulnerabilities as soon as possible (well, as soon as new vulnerabilities are known and covered by DevSecOps tools).

    * Public cloud CLI clients as there is only one version of the public cloud, and the official Docker image is likely to evolve at the same time as the APIs.

* _latest_ is **not good** for:

    * Build tools as your project is developped using one specific version of the language / the build tool, and you would like to control when you change version.

    * Infrastructure-as-Code tools for the same reason as above.

    * Acceptance tests tools as the same reason as build tools.

    * Private cloud CLI clients as you may not have installed the latest version of - say - OpenShift or Kubernetes, and you'll need to use the client CLI version that matches your servers version.

!!! Success "To summarize"

    1. Make sure you explicitely override the Docker image versions of your build, Infrastructure-as-Code, private cloud CLI clients and acceptance tests tools matching your project requirements.

    2. Be aware that sometimes your pipeline may fail (without any change from you) due to a new version of DevSecOps tool that either highlights a new vulnerability (:tada:), or due to a bug or breaking change in the tool (:poop: happens).

## Secrets managements

Most of our templates manage :lock: **secrets** (access tokens, user/passwords, ...).

* either locally in specific jobs,

* or for all jobs from one single template ([see below](#the-templates-base-job)).

## Merge Request workflow

One thing that has to be chosen with GitLab CI/CD is the [Merge Request workflow strategy](https://docs.gitlab.com/ee/ci/yaml/workflow.html#switch-between-branch-pipelines-and-merge-request-pipelines).

By default, _to be continuous_ implements the **branch pipelines** strategy, with the following workflow declaration:

```yaml

workflow:

  rules:

    # exclude merge requests

    - if: $CI_MERGE_REQUEST_ID

      when: never

    - when: always

```

If you want to switch to the **merge request pipelines** strategy, simply add the following to your `.gitlab-ci.yml` file:

```yaml

# use Merge Request pipelines rather than branch pipelines

workflow:

  rules:

    - if: '$CI_MERGE_REQUEST_ID'

    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'

      when: never

    - when: always

```

## Advanced usage - Override YAML

Sometimes, configuration via variables is not enough to tweak an existing template to fit to your needs.

{

  "$schema": "https://docs.renovatebot.com/renovate-schema.json",

  "extends": [

    "config:base"

    "config:base",

    ":disableDependencyDashboard"

  ]

}