Commit c1e5f505 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

Merge branch 'docs/gitlab-alerts' into 'master' 

docs: replace MkDocs admonitions with GitLab alerts

See merge request to-be-continuous/doc!112
parents 906c7a97 51f2f7ec

docs/community.md

+6 −7
Original line number Diff line number Diff line
@@ -36,13 +36,12 @@ If you like it, please say it! 
Consider this as our rewarding.

Thanks in advance 🙏 



!!! TIP "To star all TBC templates all at once"



    ```BASH

    curl -sSf "https://gitlab.com/api/v4/groups/to-be-continuous/projects?per_page=100" | jq -r '.[].id' | while read pid; do curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$pid/star"; done

    ```



    :bulb: requires `curl` & `jq`

> [!tip] To star all TBC templates all at once

> ```BASH

> curl -sSf "https://gitlab.com/api/v4/groups/to-be-continuous/projects?per_page=100" | jq -r '.[].id' | while read pid; do curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$pid/star"; done

> ```

>

> :bulb: requires `curl` & `jq`



## Let's Talk!

docs/dev/guidelines.md

+52 −52
Original line number Diff line number Diff line
@@ -20,30 +20,30 @@ In order to prevent job names overlap between several templates, each template s 


For readability reason in the graphical representation of the pipeline, that prefix shall be as short as possible (5 letters max).



!!! EXAMPLE

    `mvn` for Maven, `cf` for Cloud Foundry, `os` for OpenShift, `k8s` for Kubernetes, `ng` for Angular

> [!note] Example

> `mvn` for Maven, `cf` for Cloud Foundry, `os` for OpenShift, `k8s` for Kubernetes, `ng` for Angular



### jobs naming



Jobs shall adopt [kebab-case](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) convention: lowercase words 

separated by hyphens.



!!! EXAMPLE

    `xxx-build`, `xxx-test`, `xxx-code-quality`

> [!note] Example

> `xxx-build`, `xxx-test`, `xxx-code-quality`



### variables naming



**Global variables** used and defined by a template shall adopt [SCREAMING_SNAKE_CASE](https://en.wikipedia.org/wiki/Snake_case)

convention: uppercase words separated by underscores, and shall be prefixed with the template name or the name of the related tool.



!!! EXAMPLE

    `MAVEN_CLI_OPTS`, `DOCKER_CLAIR_ADDR`, `SONAR_HOST_URL`

> [!note] Example

> `MAVEN_CLI_OPTS`, `DOCKER_CLAIR_ADDR`, `SONAR_HOST_URL`



It also may happen that some templates evaluate and export (dynamic) **local variables**.

They shall adopt [snake_case](https://en.wikipedia.org/wiki/Snake_case) convention: lowercase words separated by underscores.



!!! EXAMPLE

    `hostname` variable dynamically evaluated and exported by OpenShift template during deployment jobs

> [!note] Example

> `hostname` variable dynamically evaluated and exported by OpenShift template during deployment jobs



## Job prototype
@@ -54,22 +54,22 @@ that defines: 
* the default image to use (variabilized)

* common cache policy



!!! EXAMPLE

    ```yaml

    # xxx job prototype

    .xxx-base:

      image: $XXX_IMAGE

      services:

        # this image performs usage tracking

        - name: "$TBC_TRACKING_IMAGE"

          command: ["--service", "xxx", "1.0.0"] # 2nd arg: template name; 3rd arg: template version 

      # Cache downloaded dependencies and plugins between builds.

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

      cache:

        key: "$CI_COMMIT_REF_SLUG-xxx"

        paths:

          - binaries/

    ```

> [!note] Example

> ```yaml

> # xxx job prototype

> .xxx-base:

>   image: $XXX_IMAGE

>   services:

>     # this image performs usage tracking

>     - name: "$TBC_TRACKING_IMAGE"

>       command: ["--service", "xxx", "1.0.0"] # 2nd arg: template name; 3rd arg: template version 

>   # Cache downloaded dependencies and plugins between builds.

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

>   cache:

>     key: "$CI_COMMIT_REF_SLUG-xxx"

>     paths:

>       - binaries/

> ```



:information_source: the hidden base job is not required for templates implementing only one job.
@@ -81,34 +81,34 @@ our templates flexible is to use global variables that can be overridden. 
The most obvious example is the docker image used by the jobs, that shall be variabilized.

But command line arguments shall be defined globally too, and overridable by users.



!!! EXAMPLE

    ```yaml

    variables:

      # Docker image is variabilized and can be overridden

      XXX_IMAGE: xxx:latest

      # my build arguments are variabilized and can be overridden

      XXX_BUILD_ARGS: 'build --with-default-args'

      

    # xxx job prototype

    .xxx-base:

      image: $XXX_IMAGE

      services:

        # this image performs usage tracking

        - name: "registry.gitlab.com/to-be-continuous/tools/tracking:master"

          command: ["--service", "xxx", "1.0.0"] # 2nd arg: template name; 3rd arg: template version 

      # Cache downloaded dependencies and plugins between builds.

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

      cache:

        key: "$CI_COMMIT_REF_SLUG-xxx"

        paths:

          - binaries/

    

    xxx-build:

      extends: .xxx-base

      stage: build

      script:

        - xxx $XXX_BUILD_ARGS

    ```

> [!note] Example

> ```yaml

> variables:

>   # Docker image is variabilized and can be overridden

>   XXX_IMAGE: xxx:latest

>   # my build arguments are variabilized and can be overridden

>   XXX_BUILD_ARGS: 'build --with-default-args'

>   

> # xxx job prototype

> .xxx-base:

>   image: $XXX_IMAGE

>   services:

>     # this image performs usage tracking

>     - name: "registry.gitlab.com/to-be-continuous/tools/tracking:master"

>       command: ["--service", "xxx", "1.0.0"] # 2nd arg: template name; 3rd arg: template version 

>   # Cache downloaded dependencies and plugins between builds.

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

>   cache:

>     key: "$CI_COMMIT_REF_SLUG-xxx"

>     paths:

>       - binaries/

> 

> xxx-build:

>   extends: .xxx-base

>   stage: build

>   script:

>     - xxx $XXX_BUILD_ARGS

> ```



## Kicker descriptor

docs/dev/workflow.md

+2 −2
Original line number Diff line number Diff line
@@ -31,8 +31,8 @@ $ git commit -s -m 'This is the commit message' 


## Contribute to an existing template



!!! INFO

    All submissions, including submissions by project members, need to be reviewed before being merged.

> [!note]

> All submissions, including submissions by project members, need to be reviewed before being merged.



To contribute:

docs/secu/index.md

+10 −12
Original line number Diff line number Diff line
@@ -46,21 +46,19 @@ You should either : 
    - upgrade tools and important components regularly with safe updates

    - root-less image are best to prevent some container escalation vulnerabilities against your runner provider



!!! tip



    Whenever building your own image or using an upstream image, you can use [Renovate](https://docs.renovatebot.com/) to watch updates for your tools, test the new version and integrate them seamlessly.

> [!tip]

> Whenever building your own image or using an upstream image, you can use [Renovate](https://docs.renovatebot.com/) to watch updates for your tools, test the new version and integrate them seamlessly.



## Vulnerability Reports (Trivy)



!!! warning



    When reviewing vulnerabilities from containers, you have to consider the following principes :



    - containers are usually very short-lived in a CI/CD environment

    - no direct user access is possible 

    - most job does not expose any exteral services (i.e. HTTP server) making attacks reliant on user interaction very hard if not impossible to exploit

    

    In short, risks are often low in **the CI/CD context** but carefully reviewing vulnerabilities are an essential step to secure your pipeline.

> [!important]

> When reviewing vulnerabilities from containers, you have to consider the following principes :

>

> - containers are usually very short-lived in a CI/CD environment

> - no direct user access is possible 

> - most job does not expose any exteral services (i.e. HTTP server) making attacks reliant on user interaction very hard if not impossible to exploit

>

> In short, risks are often low in **the CI/CD context** but carefully reviewing vulnerabilities are an essential step to secure your pipeline.



Here are vulnerability reports for each default image used by _to be continuous_ templates (generated every day):

docs/self-managed/basic.md

+24 −24
Original line number Diff line number Diff line
@@ -38,25 +38,25 @@ Don't panic, we provide all required tools to initiate it for the first time, an 


That should take a while, but hopefully at the end you'll have cloned the complete _to be continuous_ group and projects :tada:.



!!! WARNING "Installing _to be continuous_ in a custom root group"

    By default and preferably, _to be continuous_ shall be installed:



    * in the `to-be-continuous` root group on your GitLab server,

    * with **public** visibility.



    If one or both of these requirements can't be met (because you're not allowed to create a root group in your organization and/or 

    not allowed to create projects with public visibility), please 

    [read the advanced usage chapter](./advanced.md#installing-tbc-in-a-custom-group).

> [!important] Installing _to be continuous_ in a custom root group

> By default and preferably, _to be continuous_ shall be installed:

>

> * in the `to-be-continuous` root group on your GitLab server,

> * with **public** visibility.

>

> If one or both of these requirements can't be met (because you're not allowed to create a root group in your organization and/or 

> not allowed to create projects with public visibility), please 

> [read the advanced usage chapter](./advanced.md#installing-tbc-in-a-custom-group).



## Build the tracking image



!!! WARNING "Deprecated"

    _to be continuous_ used to need the [tracking](https://gitlab.com/to-be-continuous/tools/tracking) Docker image to be successfully built and available locally in your

    Docker registry because it is used as a [service container](https://docs.gitlab.com/ci/services/) by all templates.



    This is no longer required as in its latest versions, TBC - by default - is not pulling the image anymore.



    This can be overridden. For more info, please [read the advanced usage chapter](./advanced.md#setup-tracking).

> [!important] Deprecated

> _to be continuous_ used to need the [tracking](https://gitlab.com/to-be-continuous/tools/tracking) Docker image to be successfully built and available locally in your

> Docker registry because it is used as a [service container](https://docs.gitlab.com/ci/services/) by all templates.

>

> This is no longer required as in its latest versions, TBC - by default - is not pulling the image anymore.

>

> This can be overridden. For more info, please [read the advanced usage chapter](./advanced.md#setup-tracking).



## Sync. your local copy of tbc
@@ -71,14 +71,14 @@ For this, you only have to create a [scheduled pipeline](https://docs.gitlab.com 


All other required variables will be automatically retrieved from [GitLab CI predefined variables](https://docs.gitlab.com/ci/variables/predefined_variables/).



!!! WARNING

    From this point, you might not make any commit in any local copy of _to be continuous_ projects

    because it will get overwritten every night.



    If you need to modify template code, you'll have 2 options depending on your case:



    * if it's a general enhancement/fix: make a contribution to the Open Source [to be continuous project](https://gitlab.com/to-be-continuous/) and get the change through the synchronization task,

    * if it's a change specific to your company: see [advanced usage](advanced.md)

> [!important]

> From this point, you might not make any commit in any local copy of _to be continuous_ projects

> because it will get overwritten every night.

>

> If you need to modify template code, you'll have 2 options depending on your case:

>

> * if it's a general enhancement/fix: make a contribution to the Open Source [to be continuous project](https://gitlab.com/to-be-continuous/) and get the change through the synchronization task,

> * if it's a change specific to your company: see [advanced usage](advanced.md)



By the way, you can manually trigger a pipeline in your [tools/gitlab-sync](https://gitlab.com/to-be-continuous/tools/gitlab-sync) project

anytime to synchronize your _to be continuous_ copy.