* Variables naming convention (to be defined, should we require the job name uppercase as prefix for all variables ? Think about a way to verify variables in hub pipeline and permit various configuration for on-premise #231)
### Choose the best docker image
* Check if there is an image dedicated for the tool to run in the job
* Check if the image is official (+++)
* Check if the image is maintained (++)
* Check if the image is largely used (++)
* Check if the image is efficient to run the job (++) *difficult to check for the user*
* Check if the image use the latest version of the tool (how to check it automatically)(+)
* Check the size (smallest is the best, it should only contain essential tools, KISS) (+)
* Check if the image has versioning (not only latest) (-)
* If no, check if there is an image already setup for the language of the tool (python, node, go...)
* Check if the image is official (+++)
* Check if the image is maintained (++)
* Check if the image is largely used (++)
* Check if the image is efficient to run the job (++) *difficult to check for the user*
* Check the size (smallest is the best, it should only contain essential tools, KISS) (+)
* Check if the image has versioning (not only latest) (-)
* Install the tool in the image using package manager (fixed version)
* If no, use docker alpine and install tool in it. If the installation is too long in the job: create your own image (fixed version)
### About versions:
> The installed version of Doxygen must be specified as variable with the default value on the current latest version 1.8.18-r0
> A fixed tag must be specified for the alpine image used
### 🧮 Variables
In order to be customizable, your job should use `variables`. This section
permits to define environment variables, usable by the job script.
!!! tip
Set default values to your variables to reflect the most common use-case,
in this way, your job will remains plug-and-play while being customizable
| `NEWMAN_COLLECTION` <img width=100/> | Name of the Postman collection <img width=175/> | `postman_collection.json` <img width=100/> |
| `NEWMAN_GLOBALS_FILE` | Name of the Postman globals file for [variables](https://learning.postman.com/docs/sending-requests/variables/) | ` ` |
| `NEWMAN_ADDITIONAL_OPTIONS` | Other [options](https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/) you may want to use with Newman | ` ` |
| `NEWMAN_FAIL_ON_ERROR` | Fail job on a request/test error | `true` |
| `NEWMAN_ITERATIONS_NUMBER` | Number of Newman iterations to run (see [documentation](https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/#misc)) | `2` |
### 🐳 Choose a Docker image
### About process:
!!! info
As described in [our guidelines](#guidelines), all jobs are run inside a
container instance, so they must specify Docker image to use. Depending of
your job, it can be tricky to find the perfect image.
The better place to found a docker image is the [docker
hub](https://hub.docker.com/search?q=&type=image). You can start your research
there with following steps :
1. Search for an image prepared with the tool you want to run
* This is the preferred situation with a ready-to-use docker image that
In this case, you need to use `when: always` option under `artifacts`
if you want to expose result even if job fails.
This is a way to quickly integrate any format of report in Gitlab Merge
Request interface. Technically, you don't have to format your report ouput
in a specific format but we recommend to use `HTML` format. In this way,
the report is one-click readable from any Merge Request.
??? example "Example of `artifacts:expose_as` report"
Example: job [`trivy_image`](/jobs/dynamic_tests/trivy_image/) that
use its output as `junit` report in `artifacts:repors:junit` section:
```yaml
nmap:
[...]
artifacts:
expose_as: "nmap-report"
paths:
- "${HTML_OUTPUT}"
when: always
```
Then, run doxygen like : - doxygen $DOXYGEN_CONFIGURATION
3. Simple artifact without integration
### About artifact:
!!! info
In this case, you need to use `when: always` option under `artifacts`
if you want to expose result even if job fails.
??? example "Example of `artifacts`"
Example: job [`trivy_image`](/jobs/dynamic_tests/trivy_image/) that
use its output as `junit` report in `artifacts:repors:junit` section:
```yaml
job_name:
[...]
artifacts:
paths:
- "output"
when: always
```
* Use expose_as like in mkdocs job to expose the artifact in the MR
> integration in MR widget ? expose_as ?
> artifact retention
### Compliance with another job
### About compliance with pages job:
* Compliance with another job
* Compliance with pages
Add this job to the list of documentation builder jobs in pages documentation
The documentation output must be specified in a variable with the default value to documentation_build/ in order to be retrieved by pages job by default
@@ -183,11 +303,6 @@ TODO
> Note about including a local job file
### Job definition of done
TODO
### Advises to keep your job generic
TODO
@@ -203,12 +318,8 @@ TODO
* Usage of `rules`, `before_script`, `after_Script`, ...
### Continuous integration pipeline
TODO: describe our CI/CD pipeline
### TODO
### TODO in another issue
* Stage list in job file with only one stage: the one of the job
