Skip to content

Structure of official job repo

Our jobs are stored in the R2Devops hub repository inside the jobs folder, and follow this standardized structure:

.
└── jobs
    └── <job_name>
        ├── <job_name>.yml        # Job definition
        ├── CHANGELOG.md          # Job changelog
        └── README.md             # Job documentation

A template of job is available in the R2Devops hub repository.

🤖 Job definition

This file must have the same name as the job with the yml extension: <job_name>.yml. It contains the GitLab job configuration in yaml format.

The jobs of the hub use the GitLab CI/CD configuration format. They must specify a Docker image to be run in a container.

Info

If you are curious and want to know more about the job definition, you can go to:

A job definition usually contains the following fields:

  • image: this is the docker image used to run the job.
  • stage (mandatory): this is the default stage for the job. You can choose it in our default stage list.
  • script (mandatory): this is the heart of the job. It contains a list of shell commands that run the job.
  • variables: in this field, you will find all the variables used by the script of the job. This is where you customize its behavior.
  • artifacts: it specifies the result of the job that should be exposed to the user through classic artifacts or Gitlab reports.

Here is an example of job definition apidoc.yml 👇

apidoc:
  image:
    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:
    - npm install [email protected]$APIDOC_VERSION -g
    - apidoc -c "$APIDOC_CONFIG_PATH" -o "$APIDOC_OUTPUT_PATH" -t "$APIDOC_TEMPLATE_PATH"
  artifacts:
    when: always
    expose_as: "apiDoc build"
    paths:
      - "$APIDOC_OUTPUT_PATH"

📚 Job documentation

This file, named README.md, contains the documentation of a job in markdown format.

Info

The documentation explains what the job does, how to use it and to customize it. A clear documentation is important: no one wants to use a job when you can't understand what it is for!

## Objective

Creates a versioned HTML documentation from API annotations in your source
code using [apiDoc](https://www.apidocjs.com/).

## How to use it

1. Prepare your project with API annotations in your source code following
   [apiDoc format](https://apidocjs.com/#examples) and your [apiDoc
   configuration file](https://apidocjs.com/#configuration).
2. Choose a version in [version list](#changelog)
3. Add the corresponding URL to your `.gitlab-ci.yml` file (see [Getting
   started](/use-the-hub/)). Example:
    ```yaml
    include:
    - remote: 'https://api.r2devops.io/job/r/r2devops-bot/apidoc'
    ```
4. If you need to customize the job (stage, variables, ...) 👉 check the
   [jobs customization](/use-the-hub/#jobs-customization)
5. Well done, your job is ready to work ! 😀

## Variables

| Name | Description | Default |
| ---- | ----------- | ------- |
| `APIDOC_VERSION` | Version of apiDoc to use | `0.24.0` |
| `APIDOC_CONFIG_PATH` | Path to config file or to directory containing config file (apidoc.json or apidoc.config.js) | `.` |
| `APIDOC_OUTPUT_PATH` | Output directory path | `/documentation_build` |
| `APIDOC_TEMPLATE_PATH` | Path to template folder | `/usr/lib/node_modules/apidoc/template/` |

Documentation result

🏗 Job changelogs

This file, named CHANGELOG.md, contains the changelog of a job following the keep a changelog structure and using markdown.

Info

  • The jobs version should follow the semantic versioning format (MAJOR.MINOR.PATCH).
  • The first version recommended for a job is 0.1.0.
  • For each version listed in this file, you should have a corresponding git tag. Both format are supported
    • Only the version as tag name. Ex: 1.1.4
    • The job name and version, joined with a hyphen (-), as tag name. It is useful if you store several jobs in your repository. Ex: docker_build-1.1.4

Here is an example of a CHANGELOG.md file for docker_build job 👇

# Changelog
All notable changes to this job will be documented in this file.

## [1.1.0] - 2021-06-21
* Allows context different from root with new variable `DOCKER_CONTEXT_PATH`

## [1.0.0] - 2021-05-07
* Breaking change in the configuration of custom registry, see documentation
* Add support to push in multiple registries
* Add support to authentication in multiple registries

## [0.4.0] - 2021-04-19
* Add new option `--use-new-run` to kaniko executor (enabled by default)
* Update kaniko image to `v1.5.1`

## [0.3.0] - 2020-11-25
* New variable `DOCKER_USE_CACHE` to be able to cache layers of build
* New variable `DOCKER_CACHE_TTL` to define time to live of cache
* New variable `DOCKER_VERBOSITY` to set the verbosity of the build
* New variable `DOCKER_OPTIONS` to be able to add additional options

## [0.2.0] - 2020-11-02
* Add variable `DOCKERFILE_PATH` which permits specifying custom path to
  Dockerfile

## [0.1.0] - 2020-10-21
* Initial version
Last update: April 14, 2022