Commit 38d8e03d authored by Thomas Boni's avatar Thomas Boni
Browse files

update following @coconux review

parent 2ded1c16

docs/create-update-job.md

+22 −23
Original line number Diff line number Diff line
@@ -30,7 +30,10 @@ able to work on it before merging your update in the real project. 
    If you alter it, we will not be able to merge your job in `r2devops/hub`

    repository 😕



1. If you want to add a new job, create a new directory dedicated to your job in `jobs/` folder

1. If you want to add a new job, create a new directory dedicated to your job

   in `jobs/` folder. You can use the [job

   template](https://gitlab.com/r2devops/hub/-/tree/latest/tools/job_template/job_name)

   as starting point

1. Ensure to respect rules in this guide

1. Do not update the CI/CD configuration (file `.gitlab-ci.yml`)

1. Test your job and ensure it works
@@ -67,7 +70,7 @@ able to work on it before merging your update in the real project. 
       [`Contribution`](https://docs.gitlab.com/ee/user/project/merge_requests/allow_collaboration.html)

        (this isn't available for protected branches like `latest`)



!!! note "3. In the newly created MR, ensure to fulfill all steps of the [job Definition of Done](#job-definition-of-done) and tick related boxes"

!!! note "3. In the newly created MR, ensure to fulfill all steps of the job Definition of Done and tick related boxes"



Thanks a lot for your contribution 😀🎉 !
@@ -195,14 +198,11 @@ there with following steps : 
!!! note "3. If you decide to build your own image: the image must be stored in publicly reachable registry like Docker hub or Gitlab registry"





!!! summary "**General guidelines to choose the image**"

    * If the image is official (`OFFICIAL IMAGE` badge on docker hub): this is

      the perfect image for your use case

      ![Docker official badge](images/docker_official_badge.png){: .docker_official_badge }





      <div class="styles__officialImageBanner___1Ey-B styles__rightBanner___3gtom" data-testid="imageBanner" style="background-color: #8ca8b8;COLOR: white;/* padding: 4px 6px 4px 14px; */padding-top: 4px;/* margin-right: 0px; */width: 10em;padding-bottom: 2px;padding-left: 15px;"><span style="margin-right: 5px; color: white; font-weight: 600;"> Official Image</span><svg xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid meet" class="dicon   " viewBox="0 0 14 14" style="opacity: 0.7;width: 14px;height: 14px;"><g fill="#FFFFFF"><path d="M0,17.257497 L2.6406073,16.1524777 L3.79166667,18.6875 L6.5,11.8625027 C5.0781073,11.7975196 3.72394063,11.3425016 2.70833333,10.5625 L0,17.257497 Z" id="Shape"></path><path d="M10.2916667,10.5625 C9.20833333,11.3425016 7.9218573,11.7975196 6.5,11.8625027 L9.20833333,18.6875 L10.3593927,16.1524777 L13,17.257497 L10.2916667,10.5625 Z" id="Shape"></path><path d="M12.1875,5.6875 C12.1875,2.52777778 9.65972222,0 6.5,0 C3.34027778,0 0.8125,2.52777778 0.8125,5.6875 C0.8125,8.84722222 3.34027778,11.375 6.5,11.375 C9.65972222,11.375 12.1875,8.84722222 12.1875,5.6875 Z M8.71178903,8.84722222 L6.49996696,7.39376652 L4.28817792,8.84722222 L5.23611111,6.31944444 L3.34027778,5.05555556 L5.55209985,5.05555556 L6.50003304,2.52777778 L7.44796623,5.05555556 L9.65978831,5.05555556 L7.76395497,6.31944444 L8.71178903,8.84722222 Z" id="Shape"></path></g></svg></div>

**General guidelines to choose the image**



* If the image is official (`OFFICIAL IMAGE` badge on docker hub): this is the

  perfect image for your use case ![Docker official

  badge](images/docker_official_badge.png){: .docker_official_badge }

* Else, following points should be considered to choose an image:

    * The image must be versioned and not only with `latest` tag. ==If image

      isn't versioned: it's not usable for your job==
@@ -243,7 +243,7 @@ interface: 


    ??? example "Example of `artifacts:reports:junit` report"

        Job [`trivy_image`](/jobs/dynamic_tests/trivy_image/) that

        uses its output as `junit` report in `artifacts:repors:junit` section:

        uses its output as `junit` report in `artifacts:reports:junit` section:

        ```yaml

        trivy_image:

          [...]
@@ -260,8 +260,8 @@ interface: 
    the report is one-click readable from any Merge Request.



    ??? example "Example of `artifacts:expose_as` report"

        Job [`trivy_image`](/jobs/dynamic_tests/trivy_image/) that

        uses its output as `junit` report in `artifacts:repors:junit` section:

        Job [`nmap`](/jobs/dynamic_tests/nmap/) uses `artifacts:expose_as`

        to expose its `HTML` report:

        ```yaml

        nmap:

          [...]
@@ -275,8 +275,7 @@ interface: 
3. Simple artifact without integration



    ??? example "Example of `artifacts`"

        Job [`trivy_image`](/jobs/dynamic_tests/trivy_image/) that

        uses its output as `junit` report in `artifacts:repors:junit` section:

        Job that specify an `artifact`:

        ```yaml

        job_name:

          [...]

docs/css/extra.css

+0 −1
Original line number Diff line number Diff line
@@ -302,5 +302,4 @@ opacity: .8; 
.docker_official_badge{

  width: 11em;

  box-shadow: 8px 8px 12px #aaa;



}

docs/job-structure.md

+16 −15
Original line number Diff line number Diff line
@@ -5,7 +5,7 @@ repository inside the 
[`jobs`](https://gitlab.com/r2devops/hub/-/tree/latest/jobs) folder and

follow this standardized structure:



```shell

```

.

└── jobs

    └── <job_name>
@@ -46,23 +46,27 @@ Job definition usually contains the following fields: 
* **[`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables){:target="_blank"}**: variables used by the `script` part of the job to customize its behaviour

* **[`artifacts`](https://docs.gitlab.com/ee/ci/yaml/#artifacts){:target="_blank"}**: specify the result of the job that should be exposed to the user trough classic artifact or Gitlab reports



**Example of job definition [`gitleaks.yml`](https://r2devops.io/jobs/static_tests/gitleaks/):**

**Example of job definition [`apidoc.yml`](https://r2devops.io/jobs/build/apidoc/):**



```yaml

gitleaks:

  stage: static_tests

apidoc:

  image:

    name: "zricethezav/gitleaks:v6.1.2"

    name: node:12.18.3-alpine3.12

    entrypoint: [""]

  stage: build

  variables:

    APIDOC_CONFIG_PATH: '.'

    APIDOC_OUTPUT_PATH: 'website_build/'

    APIDOC_TEMPLATE_PATH: '/usr/local/lib/node_modules/apidoc/template/'

    APIDOC_VERSION: '0.24.0'

  script:

    - gitleaks -v --pretty --repo-path . --commit-from=$CI_COMMIT_SHA

      --commit-to=$CI_COMMIT_BEFORE_SHA --branch=$CI_COMMIT_BRANCH

      --report gitleaks-report.json

    - npm install apidoc@$APIDOC_VERSION -g

    - apidoc -c "$APIDOC_CONFIG_PATH" -o "$APIDOC_OUTPUT_PATH" -t "$APIDOC_TEMPLATE_PATH"

  artifacts:

    when: always

    expose_as: "gitleaks-report"

    expose_as: "apiDoc build"

    paths:

      - "gitleaks-report.json"

      - "$APIDOC_OUTPUT_PATH"

```
@@ -80,11 +84,8 @@ the following fields: 
| `maintainer` | Gitlab username of the maintainer | Yes |

| `license` | Open-source licence for the job. You can choose between `Apache-2.0` and `MIT` | Yes |

| `labels` | List of label describing the job | No |



<!-- TODO after https://gitlab.com/r2devops/hub/-/merge_requests/129

| `images` | TODO | TODO |

| `tools` | TODO | TODO |

-->

| `images` | Dict of docker image(s) used by the job. Image name as key and tag version as value | Yes |

| `tools` | Dict of tool(s) installed during the job. Name as key and version as value  | No |



**Example of `job.yml`:**