docs: add "Multiple template instantiation" chapter

## How can I override the jobs defined by _to-be-continuous_ templates?

Please read our dedicated chapter about [overriding _to-be-continuous_ templates](usage.md#advanced-usage-override-yaml) .

Please read our dedicated chapter about [overriding _to-be-continuous_ templates](usage.md#override-yaml-advanced-usage) .

## Is it possible to prevent users from overriding the included jobs configuration?

      HTTPS_PROXY: "${https_proxy}"

      NO_PROXY: "${no_proxy}"

  ```

  _(developing this requires [advanced to be continuous knowledge](../usage.md#advanced-usage-override-yaml))_

  _(developing this requires [advanced to be continuous knowledge](../usage.md#override-yaml-advanced-usage))_

2. declare it in a `kicker-extras.json` file:

  ```json

  {

## Include a template

As previously said, each template may be [included](https://docs.gitlab.com/ci/yaml/#include) in your `.gitlab-ci.yml` file using one of the 3 techniques:

As previously said, each template may be [included](https://docs.gitlab.com/ci/yaml/#include) in your `.gitlab-ci.yml` file using one of the 3 following syntaxes:

* [`include:component`](https://docs.gitlab.com/ci/yaml/#includecomponent) to use it as a [CI/CD component](https://docs.gitlab.com/ci/components/),

* [`include:project`](https://docs.gitlab.com/ci/yaml/#includeproject) to use it as a regular template,

* or [`include:remote`](https://docs.gitlab.com/ci/yaml/#includeremote) (this technique might be interesting if you want to test _to be continuous_ from your Self-Managed GitLab without installing it locally).

=== "#1: `include:component`"

For example (CI/CD component):

    The [`include:component`](https://docs.gitlab.com/ci/yaml/#includecomponent) is the newest 

    GitLab syntax and allows to use templates as a [CI/CD component](https://docs.gitlab.com/ci/components/)

    (thus configuring them with [`inputs`](https://docs.gitlab.com/ci/inputs/)):

    ```yaml

    include:

      - component: $CI_SERVER_FQDN/to-be-continuous/aws/gitlab-ci-aws@5.2

    ```

=== "#2: `include:project`"

    The [`include:project`](https://docs.gitlab.com/ci/yaml/#includeproject) syntax is the former GitLab syntax, and is very similar (except it implies configuring templates with [`variables`](https://docs.gitlab.com/ci/variables/)):

    ```yaml

    include:

      # Maven template with exact version '3.9.0'

      - project: "to-be-continuous/maven"

        ref: "3.9.0"

        file: "templates/gitlab-ci-maven.yml"

      # AWS template with minor version alias '5.2' (uses the latest available patch version)

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

        ref: "5.2"

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

    ```

=== "#3: `include:remote`"

    The [`include:remote`](https://docs.gitlab.com/ci/yaml/#includeremote) syntax might be interesting if you want to test _to be continuous_ from your Self-Managed GitLab without installing it locally (thus you'll be able to download _to be continuous_ templates directly from [gitlab.com](https://gitlab.com/to-be-continuous)).

    With this syntax, templates have to be configured with [variables](https://docs.gitlab.com/ci/variables/).

    ```yaml

    include:

      # Maven template with exact version '3.9.0'

      - remote: "https://gitlab.com/to-be-continuous/maven/-/raw/3.9.0/templates/gitlab-ci-maven.yml"

      # AWS template with minor version alias '5.2' (uses the latest available patch version)

      - remote: "https://gitlab.com/to-be-continuous/aws/-/raw/5.2/templates/gitlab-ci-aws.yml"

    ```

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

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

* _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.

    * Acceptance tests tools for 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.

> [!tip] To summarize

        - when: on_success

    ```

## Advanced usage - Override YAML

## Override YAML (Advanced Usage)

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

    # any other case: auto & allow failure

    - allow_failure: true

```

## Multiple template instantiation (Advanced Usage)

It may happen that you need to multi-instantiate a _to-be-continuous_ template in your project.

A very common case is with monorepos, when your Git repository hosts multiple independant projects.

Most of _to-be-continuous_ templates support GitLab's [`parallel:matrix` syntax](https://docs.gitlab.com/ci/yaml/#parallelmatrix) to allow multiple template instantiation.

All you have to do is to define a `parallel:matrix` configuration at the [template's base job](#the-templates-base-job) level in your `.gitlab-ci.yml` file,

and define each project specific configuration in your matrix entries.

Example (multi instanciation of the Python template):

```yaml

include:

  # Python template

  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python@8

# multi-instantiate the Python template

.python-base:

  parallel:

    matrix:

      - PYTHON_PROJECT_DIR: backends/users-api

        PYTHON_IMAGE: docker.io/library/python:3.13-slim

        PYTEST_ENABLED: true

        RUFF_ENABLED: true

      - PYTHON_PROJECT_DIR: backends/orders-api

        PYTHON_IMAGE: docker.io/library/python:3.13-slim

        NOSETESTS_ENABLED: true

      - PYTHON_PROJECT_DIR: cli/users-cli

        PYTHON_IMAGE: docker.io/library/python:3.10-slim

        PYTHON_BLACK_ENABLED: true

```

> [!important]

> As you can see in the above example, the `parallel:matrix` syntax compels to use `variables` to configure the template

> (there's no `parallel:matrix` syntax for CI/CD component's [`inputs`](https://docs.gitlab.com/ci/inputs/)).