doc(archi): dotenv artifacts

* [Custom Certificate Authority support](../usage.md#certificate-authority-configuration)

* [Scoped Variables support](../usage.md#scoped-variables)

* [`$TRACE` variable enables debug logging](../usage.md#debugging-to-be-continuous-jobs)

* [configurable production and intergation branches](../usage.md#production-and-integration-branches)

* [configurable Git references](../usage.md#configurable-git-references)

* [Merge Request Workflow](../usage.md#merge-request-workflow) by default, globally overridable

* [Adaptive Pipeline strategy](../usage.md#test-analysis-jobs-rules) by default, globally overridable

<!-- * release management & package publishing, -->

## Standard stages

Every template shall reuse defined [generic pipeline stages](../understand.md#generic-pipeline-stages).

If an additional stage seems to be required, that must be discussed with the core team first.

## Sensible defaults

Examples:

- When introducing a new toggleable feature (e.g. a new SAST job), decide wisely whether it should be enabled by default (opt-out) or disabled by default (opt-in).

- When defining default tool CLI options, select the most appropriate options. If unsure: prefer the option that raises the bar (of code quality/best practices) rather than the conservative one

## GitLab services by default

## GitLab by default

When implementing a feature requiring an external service (ex: a packages registry)

and if GitLab provides such a service, then:

- 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 include be versionned or not? both options have serious drawback (dependency hell vs. less control on impact management)

## Standard stages

Every template shall reuse defined [generic pipeline stages](../understand.md#generic-pipeline-stages).

If an additional stage seems to be required, that must be discussed with the core team first.

## Standard environments

Every infrastructure(-as-code) and deployment template shall support 4 kinds of environments (each being optional):

## Dotenv artifacts

Propagate dynamic output variables to downstream jobs...

_to be continuous_ templates are composable. In other words they cooperate gracefully with others to minimize the amount of integration work.

It is common that a job _produces_ output that could be used by downstream jobs, possibly from other templates.

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.

Examples:

TODO - TODO - TODO

- every deployment template propagates the deployed environment as a `$environment_url`, that can be used by

any acceptance testing template, whichever the deployment technology or the testing tools

- the Docker and Cloud Native Buildpack templates both propagates several variables of the built container image (container registry, full url with tag, full url with digest, tag only...) that can be used in downstream templates to use pull this image

## Non-backward compatible GitLab features

This page references GitLab CI development guidelines for people that wish to contribute with templates of their own.

## Guiding principle and rules

# _to be continuous_ architectural principles

As a template developer, you should make everything possible to honor the _guiding principles_:

!!! Success "The guiding principles"

    * continuous integration (CI) has to be **fast** (and to some extend _energy efficient_)

    * continuous deployment/delivery (CD) has to **secure** the deployment/delivery to production

!!! example "Corollary rules"

    1. the least stages, the best

    1. parallelize all jobs that can be

    1. long jobs (5 min or more) should not be auto-run by default, but rather [manually](https://docs.gitlab.com/ee/ci/yaml/#whenmanual)

       or [scheduled](https://docs.gitlab.com/ee/ci/pipelines/schedules.html). <br/>

       Projects willing to auto-run those jobs should be able to override the default.

## Stages

Every template shall reuse defined [generic pipeline stages](../understand.md#generic-pipeline-stages).

If an additional stage seems to be required, that must be discussed with the core team.

As a template developer, you should be aware of _to be continuous_ [architectural principles](./architecture.md)

as they generally apply to all templates.

## Naming conventions

_to be continuous_ templates are built to be:

* **Modular**: each template complies to the [Single-responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) while observing common architectural principles (standard behaviour per template type, generic pipeline stages, common Git workflow principles, ...)

* **Modular**: each template complies to the [Single-responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) while observing [common architectural principles](./dev/architecture.md) (standard behaviour per template type, generic pipeline stages, common Git workflow principles, ...)

* **Composable**: each template cooperates gracefully with others to minimize the amount of integration work. 

Let's illustrate this with an example.