Skip to content

Use the hub

๐Ÿ“ Prerequisites

  • ๐ŸฆŠ Manage your project in Gitlab and understand what is CI/CD with Gitlab
  • ๐Ÿ”ซ Be aware each file modification in your project can trigger a Pipeline
  • ๐Ÿ— Have access to the pipelines page in your Gitlab project and write access to your project .gitlab-ci.yml file

โณ Quick setup

Follows these steps to setup your CI/CD pipeline in less than 5 minutes !

  1. If you haven't yet a .gitlab-ci.yml file in the root on your repository: create it with the list of stages:

    stages:
      - static_tests
      - build
      - dynamic_tests
      - provision
      - review
      - release
      - deploy
      - others
    

    Info

    Check stages section to get more information about this list or if you already have a configuration with different stages.

  2. Select Jobs you want in jobs section and append their URL in the include list of your .gitlab-ci.yml file:

    include:
      - remote: 'https://jobs.r2devops.io/<job_name>.yml'
      - remote: 'https://jobs.r2devops.io/<job_name>.yml'
      - ...
    

    Note

    By default, the latest version of a job is used. You can choose to use a specific version using a tag. Available tags are described for each job in jobs section. Description of tag format is available in Versioning page.

    Once your pipeline is functional, we recommend using a specific version for jobs in order to ensure that your pipeline will not be broken by a job update.

  3. Jobs can be customized ๐Ÿ‘‰ check the jobs customization section.

  4. Everything is ready! You can now benefit the full power of a CI / CD pipeline ๐ŸŽ‰๐Ÿš€

    Tip

    You can also combine jobs templates and your own jobs in .gitlab-ci.yml configuration file.

๐Ÿค“ Pipeline examples

  • Several examples of projects using the r2devops hub:

  • An example of a full .gitlab-ci.yml configuration using jobs from the hub ๐Ÿ‘‡

    Jobs used in the example

    • Plug-and-play set of jobs from the hub to automatically build, test and deploy static documentation website:
    • Plug-and-play set of jobs from the hub to automatically build, push and test docker images:
    • A custom manual job unit_tests
    stages:
    - static_tests
    - build
    - dynamic_tests
    - provision
    - review
    - release
    - deploy
    - others
    
    # Jobs from r2devops.io (they don't need any configuration in standard cases)
    include:
    - remote: 'https://jobs.r2devops.io/latest/mkdocs.yml'
    - remote: 'https://jobs.r2devops.io/latest/lighthouse.yml'
    - remote: 'https://jobs.r2devops.io/latest/pages.yml'
    - remote: 'https://jobs.r2devops.io/0.3.0/docker_build.yml'
    - remote: 'https://jobs.r2devops.io/0.2.0/trivy_image.yml'
    
    # Locally configured job
    unit_tests:
      image: python:3.9-alpine
      stage: static_tests
      before_script:
        - pip install pipenv && pipenv --bare install --dev
      script:
        - make test
    

โ–ถ Stages

By default, each job from the hub is a part of on these stages:

  • ๐Ÿ”Ž Static_tests: static testing of repository files
  • ๐Ÿงฑ Build: building and packaging of software
  • ๐Ÿ”ฅ Dynamic_tests: dynamic testing of a running version of the software
  • ๐Ÿ›  Provision: preparation of the software infrastructure
  • ๐Ÿ‘Œ Review: deployment of the software in an isolated review environment
  • ๐Ÿท Release: releasing and tagging of the software
  • ๐Ÿš€ Deploy: deployment of the software on environments
  • ๐Ÿฆ„ Others: all other magic jobs not included in previous stages

This is an efficient and simple workflow. Nevertheless, if you want to use your own custom stage list: you can re-declare yourself the stage of any job from the hub. Follow the customization section to do it.

๐Ÿ”ง Jobs customization

Info

All jobs from the r2devops/hub specify a docker image to be run in a docker container

๐Ÿ–Œ Global

Each jobs of the hub can be customized. To do it, you have to include the job URL as usual and, in addition, override the options you want to customize.

Tip

In this way, you can override all Gitlab jobs parameters. All parameters are described in Gitlab documentation.

For example, if you want to use the trivy_image job and customize it by:

  • Redefining the stage to security to fit in your personal stages workflow
  • Set the variable TRIVY_VERSION to 0.9.1 to use this version instead of the default
  • Set the variable TRIVY_SEVERITY to CRITICAL to display only CRITICAL issues
include:
  - remote: 'https://jobs.r2devops.io/trivy_image.yml'

trivy_image:
  stage: security
  variables:
    TRIVY_VERSION: "0.9.1"
    TRIVY_SEVERITY: "CRITICAL"

โœ๏ธ Use custom stage

If you want to use your own stage name it's possible to do so when including your job. Example:

stages:
  - security

include:
  - remote: 'https://jobs.r2devops.io/trivy_image.yml'

trivy_image:
  stage: security

๐Ÿณ Advanced: services

You may want one of your job to interact with a container instance (API, database, web server...) to work. GitLab has an option to run a container next to a job: services.

To use this option, you must have access to an image of the container you want to run as a service. For example, if you are using our docker_build job to build an image of your application, and you want to test this image using the nmap job, just add the following configuration in your .gitlab-ci.yml file:

Info

  • The name option must contain your image name and tag or an image name from Docker Hub.
  • The alias option permits to the job to reach your application using a name. This name must be the same that the one specified inside the job target's variable.
  • You may also run some other services like a database depending on your application needs.
nmap:
  services:
    - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
      alias: app

๐ŸŽถ Multiple usage of the same job in your pipeline

If you want to reuse a job on the hub, for example launching apiDoc to build 2 API documentations in the same pipeline:

You can easily do so with Hub's jobs using extends GitLab keyword.

stages:
  - build

include:
  - remote: 'https://jobs.r2devops.io/0.2.0/apidoc.yml'

apidoc:
  variables:
    APIDOC_CONFIG_PATH: src/doc/project1/apidoc.json
    APIDOC_OUTPUT_PATH: website_build/apidoc/project1/

apidoc_project2:
  extends: apidoc
  variables:
    APIDOC_CONFIG_PATH: src/doc/project2/apidoc.json
    APIDOC_OUTPUT_PATH: website_build/apidoc/project2/

Warning

Be aware to have different artifacts path not to overwrite your first artifact by the second one.


Last update: March 8, 2021