Skip to main content

Use templates

⏳ Quick use
  1. Go to the R2Devops Marketplace and search for templates you want.
  2. Click on the template card and copy past the "Quick use" code in your gitlab-ci.yml file.
  3. You can now run your pipeline 🎉

⚙️ Setup​

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

  1. Select the templates you want in the Marketplace and append them in the include list of your .gitlab-ci.yml file:

    include:
       - project: '<project_path>'
          ref: '<version>'
          file: '<template_path>'
       - project: '<project_path>'
          ref: '<version>'
          file: '<template_path>'
      - ...

  2. The templates can be customized 👉 check the templates customization section.

  3. Everything is ready! You can now benefit the full power of a CI/CD pipeline 🎉🚀

    note

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

🤓 Pipeline examples​

  • An example of a full .gitlab-ci.yml configuration using templates from the marketplace 👇

    Templates and jobs used in the example

    _ Plug-and-play set of templates from the marketplace to automatically build, test and deploy static documentation website: _ mkdocs (latest version) _ lighthouse (latest version) _ pages (latest version) _ Plug-and-play set of templates from the marketplace to automatically build, push and test docker images: _ docker_build (version 0.3.0) _ trivy_image (version 0.2.0) _ A custom manual job unit_tests

    stages:
      - build
      - tests
      - provision
      - review
      - release
      - deploy
      - others

    # Templates from r2devops.io (they don't need any configuration in standard cases)
    include:
      - project: 'r2devops/hub'
        ref: 'mkdocs@1.8.1'
        file: 'jobs/mkdocs/mkdocs.yml'
      - project: 'r2devops/hub'
        ref: 'lighthouse@latest'
        file: 'jobs/lighthouse/lighthouse.yml'
      - project: 'r2devops/hub'
        ref: 'pages@latest'
        file: 'jobs/pages/pages.yml'
      - project: 'r2devops/hub'
        ref: 'docker_build@latest'
        file: 'jobs/docker_build/docker_build.yml'
      - project: 'r2devops/hub'
        ref: 'trivy_image@latest'
        file: 'jobs/trivy_image/trivy_image.yml'

    # Locally configured job
    unit_tests:
      image: python:3.9-alpine
      stage: tests
      before_script:
        - pip install pipenv && pipenv --bare install --dev
      script:
        - make test

🔢 Versioning​

To retrieve a template version, choose among following syntaxes:

  • To have always the latest version use: @latest
  • You can otherwise precise an exact version: @<version> (ex: @1.2.3)
  • To use the latest version of minor releases with a precise major: @~<major> (ex: @~1)
  • Or the latest version of patch releases with a precise major and minor: @~<major>.<minor> (ex: @~1.2)

🔧 Templates customization​

info

All the templates like the ones coming from the r2devops/hub specify a docker image to be run in a docker container.

🖌 Global​

Some templates can be customized. To do it, you have to include the template as usual and, in addition, override the options you want to customize.

tip

This way, you can override all Gitlab templates parameters. All parameters are described in Gitlab documentation.

For example, if you want to use the trivy_image template 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:
  - project: 'r2devops/hub'
    ref: 'trivy_image@1.3.2'
    file: 'jobs/trivy_image/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 template. Example:

stages:
  - security

include:
  - project: 'r2devops/hub'
    ref: 'trivy_image@1.3.2'
    file: 'jobs/trivy_image/trivy_image.yml'

trivy_image:
  stage: security

🐳 Advanced: services​

You may want one of your template to interact with a container instance (API, database, web server...) to work. GitLab has an option to run a container next to a template: 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 template to build an image of your application, and you want to test this image using the nmap template, 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 template to reach your application using a name. This name must be the same that the one specified inside the template 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 template in your pipeline​

If you want to reuse a template from the marketplace, for example launching apiDoc to build 2 API documentations in the same pipeline, you can easily do so with the Marketplace's templates using ==extends== GitLab keyword.

stages:
  - build

include:
  - project: 'r2devops/hub'
    ref: 'apidoc@1.3.2'
    file: 'jobs/apidoc/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 to not overwrite your first artifact by the second one.