Commit 8d851a49 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

doc(archi): GitLab services by default

parent 261cac71
Loading
Loading
Loading
Loading
+33 −5
Original line number Diff line number Diff line
@@ -14,8 +14,8 @@ Here is the list of common _to be continuous_ features that must be implemented
* [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)
* [Merge Request Workflow by default, globally overridable](../usage.md#merge-request-workflow)
* [Adaptive Pipeline strategy by default, globally overridable](../usage.md#test--analysis-jobs-rules)
* [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, -->

@@ -26,6 +26,20 @@ 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

When implementing a feature requiring an external service (ex: a packages registry)
and if GitLab provides such a service, then:

- Everything must be done to configure the feature to use GitLab's service by default (zero config).
- If not possible, at least all the required documentation shall be added to the `README.md` to explain what has to be done to configure the GitLab service properly.

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 right template perimeter

_to be continuous_ provides templates organized around languages and technologies.
@@ -67,7 +81,17 @@ Every infrastructure(-as-code) and deployment template shall support 4 kinds of
| **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) |

## Latest container images version by default
## Container images

### Explicit official image registry

Not specifying explicitly the official image registry in the image name enables a supply 
chain attack by pushing a malicious image with the same name in alternate registries
and expect a mirror will pick one of the alternate registries before the official one.

In order to protect against this kind of attacks, _to be continuous_ always use fully qualified image names (i.e. including the registry).

### Latest version by default

As stated in [our documentation](../usage.md#docker-images-versions), _to be continuous_ templates use required tools as container images.
And when available, the _latest_ version is used.
@@ -86,6 +110,8 @@ This choice is for performance reasons, as testing often requires to build first

_to be continuous_ templates features many tools that produce reports (testing tools, SAST, DAST, linters, vulnerability scanners...).

### Report formats

We decided that those tools:

- must **always** produce the textual (human readable) report in the console,
@@ -93,7 +119,9 @@ We decided that those tools:
- 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.sonarqube.org/latest/analyzing-source-code/test-coverage/overview/#test-execution-reports), [coverage report](https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/overview/#coverage-support) and [third-party issues](https://docs.sonarqube.org/latest/analyzing-source-code/importing-external-issues/importing-third-party-issues/))
- 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/)

The output report file path must also comply to the following **convention**:
### Report files naming convention

The output report file path must comply to the following **convention**:

```
<project_root_dir>/reports/<job_name>.<format_name>.<extension>`
@@ -113,7 +141,7 @@ Propagate dynamic output variables to downstream jobs...

TODO - TODO - TODO

## Preserve a reasonable rollout time before implementing non-backward compatible GitLab features
## Non-backward compatible GitLab features

Some GitLab features are not backward compatible. 
For instance features that introduce a new keyword that would break the `.gitlab-ci.yml` validation on