docs: document include:component

## How does it work?

_to be continuous_ templates rely on the GitLab CI [`include:file` feature](https://docs.gitlab.com/ee/ci/yaml/#includefile).

Any template may be included in your `.gitlab-ci.yml` file as (for e.g.):

Any _to be continuous_ template may be [included](https://docs.gitlab.com/ee/ci/yaml/#include) in your `.gitlab-ci.yml` file using one of the 3 techniques:

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

    ```yaml

    include:

      # <gitlab-host>/to-be-continuous/<project>/<template>@<version>

      - component: gitlab.com/to-be-continuous/maven/gitlab-ci-maven@3.9.0

    ```

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

    ```yaml

    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: '3.9.0' # template version

    ```

* or [`include:remote`](https://docs.gitlab.com/ee/ci/yaml/#includeremote):

    ```yaml

    include:

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

    ```

    :information_source: _this technique might only be of interest if you want to test _to be continuous_ from your Self-Managed GitLab without installing it locally_

## Include a template

As previously said, each template may be used by [including](https://docs.gitlab.com/ee/ci/yaml/#includefile) it to your

`.gitlab-ci.yml` file.

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

For example:

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

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

* or [`include:remote`](https://docs.gitlab.com/ee/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).

For example (CI/CD component):

```yaml

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 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)

  # Maven template with exact version '3.9.0'

  - component: gitlab.com/to-be-continuous/maven/gitlab-ci-maven@3.9.0

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

  - component: gitlab.com/to-be-continuous/aws/gitlab-ci-aws@5.2

```

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

## Configure a template

Each template comes with a predefined configuration (whenever possible), but is always overridable via [variables](https://docs.gitlab.com/ee/ci/variables/).

Each template comes with a predefined configuration (whenever possible), but is always overridable:

* with [inputs](https://docs.gitlab.com/ee/ci/components/index.html#use-a-component) if using the [`include:component`](https://docs.gitlab.com/ee/ci/yaml/#includecomponent) technique,

* or with [variables](https://docs.gitlab.com/ee/ci/variables/) if using `include:project`](https://docs.gitlab.com/ee/ci/yaml/#includeproject) or [`include:remote`](https://docs.gitlab.com/ee/ci/yaml/#includeremote).

Some template features are also enabled by defining the right variable(s).

### Use as a CI/CD component

Here is an example of a Maven project that:

1. overrides the Maven version used (with `image` input),

2. overrides the build arguments (with `build-args`),

3. enables [SonarQube](https://www.sonarqube.org/) analysis (by defining the `sonar-url` input and the `SONAR_AUTH_TOKEN` secret variable),

```yaml

include:

  # 1: include the component

  - component: gitlab.com/to-be-continuous/maven/gitlab-ci-maven@3.9.0

    # 2: set/override component inputs

    inputs:

      # use Maven 3.6 with JDK 8

      image: "maven:3.6-jdk-8"

      # use 'cicd' Maven profile

      build-args: 'verify -Pcicd'

      # enable SonarQube analysis

      sonar-url: "https://mysonar.domain.my"

      # SONAR_AUTH_TOKEN defined as a secret CI/CD variable

```

### Use as a regular template

Here is an example of a Maven project that:

1. overrides the Maven version used (with `MAVEN_IMAGE` variable),

3. enables [SonarQube](https://www.sonarqube.org/) analysis (by defining `SONAR_URL` and `SONAR_AUTH_TOKEN`),

```yaml

# 1: include the template(s)

include:

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

    ref: '3.9.0'

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

    ref: '1.0.0'

# 2: set/override template variables

variables:

  # use Maven 3.6 with JDK 8

  MAVEN_IMAGE: "maven:3.6-jdk-8"

```yaml

include:

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

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

    ref: '4.0.0'

  - component: gitlab.com/to-be-continuous/golang/gitlab-ci-golang@4.8.1

# hard disable go-mod-outdated

go-mod-outdated:

```yaml

include:

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

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

    ref: '5.4.0'

  - component: gitlab.com/to-be-continuous/docker/gitlab-ci-docker@5.7.0

# allow docker-trivy to fail

docker-trivy: