Skip to content

Manage template catalog

What is a catalog?

A Catalog in R2Devops is a registry of GitLab CI/CD templates sourced from a git repository.

🔎 Guides

💾 Create a catalog

Info

  • Sources of R2Devops catalogs are GitLab repositories
  • You can store several templates per repository
  • You must have at least Maintainer access
  1. Create a GitLab repository
  2. In this repository:
    1. Create R2 file
    2. Create CI/CD configuration
    3. (optional) Create documentation file
    4. (optional) Setup versioning
    5. (optional) Create changelog file
  3. Login on R2Devops
  4. In "Catalog Sources" page: import your repository

🔄 Update a catalog

  1. Update your template(s) in the GitLab repository
  2. Create new version tag
  3. Login on R2Devops
  4. In "Catalog Sources" page: click on refresh button

❌ Delete a catalog

  1. Login on R2Devops
  2. In "Catalog Sources" page: click on delete button

⚙️ Template R2 file

Each template on R2Devops must have its own R2 file. It defines template metadata.

  • It can be located anywhere in a repository
  • It uses the YAML format
  • File extension have to be .r2.yml
  • The file name is the template name

Example of R2 file docker_build.r2.yml for the template docker_build

files:
    template: ./docker_build/docker_build.yml
    documentation: ./docker_build/README.md
    changelog: ./docker_build/CHANGELOG.md
data:
    description: "Build and publish a Docker image"
    icon: 🐳
    public: false
    labels:
    - Docker
    - Build
    license: MIT
    deprecated: false
Keyword Description Default
files:template (Mandatory) Relative path(*) to the template CI/CD configuration
files:documentation Relative path(*) to the documentation file
files:changelog Relative path(*) to the changelog file
data:description The template description
data:icon Icon of the template (see emoji list) 📋
data:public true: template is public visible for everyone, false: template is private and accessible only for members of organization false
data:labels List of template labels (see list of available labels below) []
data:license The template license
data:deprecated Set the template as deprecated false

(*) Relative path

Path of files is relative from the location of the R2 file

Available labels
  • Gitlab
  • Security
  • SAST
  • Golang
  • Test
  • Lint
  • Gradle
  • Code Quality
  • Code Performance
  • Sonarqube
  • Npm
  • Utilities
  • Java
  • Maven
  • Dependency management
  • PHP
  • Composer
  • Python
  • Spelling
  • Twig
  • Yarn
  • API
  • Documentation
  • Build
  • Container
  • Docker
  • .NET
  • Laravel
  • Robustness
  • DAST
  • Terraform
  • Configuration
  • Helm
  • Kubernetes
  • Release
  • Artisan
  • Database
  • AWS
  • S3
  • Deploy

🛠️ Template CI/CD conf

This file, usually named with the template name with .yml extension contains GitLab CI/CD configuration in yaml format. It can contains any piece of configuration, from one keyword to a full pipeline. More info:

Example of CI/CD conf

docker_build:
  stage: build
  image:
    name: gcr.io/kaniko-project/executor:${IMAGE_TAG}
    entrypoint: [""]
  variables:
    COMMIT_CREATE_LATEST: "false"
    DOCKER_CONTEXT_PATH: ""
    DOCKERFILE_PATH: "Dockerfile"
    IMAGE_TAG: "v1.8.1-debug"
  script:
    - echo "Truncated example of script"

📚 Template documentation

This file, usually named README.md, contains the documentation of a template in markdown format. It should explains what the template does, how to use it and to customize it. A clear documentation is important: no one wants to use a template without it.

Example of documentation

## Objective

Build a container image of your application from a Dockerfile at the root of
your project, and push it to a remote registry or multiple ones. This is done
using [kaniko](https://github.com/GoogleContainerTools/kaniko).

## How to use it

1. Create a
[Dockerfile](https://docs.docker.com/get-started/part2/#sample-dockerfile)
(by default at the root of your project) to containerize your application
2. Include template in your CI/CD conf (see quick use above)
3. Customize the template if it's relevant

## Variables

| Name | Description | Default |
| ---- | ----------- | ------- |
| `COMMIT_CREATE_LATEST` | In a commit context, also update `latest` tag | `false` |
| `DOCKER_CONTEXT_PATH` | Path of build context from to repository root | ` ` |
| `DOCKERFILE_PATH` | Path to Dockerfile from the build context | `Dockerfile` |

📄 Template versioning

A template is versioned using git tag named like: <job_path>@<version>

Example

  • Version 0.1.0, template docker_build, R2 file located in jobs/docker_build.r2.yml
  • ➡️ The tag is jobs/docker_build@0.1.0.

Note

  • The version latest is created using the HEAD of default branch
  • Versions should follows the semantic versioning (MAJOR.MINOR.PATCH)
  • The first version recommended for a template is 0.1.0
  • Several templates can be versioned in the same repository

In order to create automatically versioning tags for your templates, you have to create a changelog file for each templates and add the template template_release in your repository CI/CD configuration.

🏗 Template changelog

This file, usually named CHANGELOG.md, contain the changelog of a template following the keep a changelog structure and using markdown syntax.

Example of changelog

# Changelog

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

## [0.3.0] - 2023-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] - 2023-11-02
* Add variable `DOCKERFILE_PATH` which permits specifying custom path to
Dockerfile

## [0.1.0] - 2023-10-21
* Initial version
Last update: February 17, 2023