Skip to main content

Manage templates

What is a marketplace?

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

🔎 Guides

💾 Create a marketplace

info
  • Sources of R2Devops marketplace 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 "Import templates" page: import your repository

🔄 Update marketplace resources

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

❌ Delete marketplace resources

  1. Login on R2Devops
  2. In "Import templates" 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: 🐳
labels:
- Docker
- Build
license: MIT
deprecated: false
KeywordDescriptionDefault
files:template(Mandatory) Relative path(*) to the template CI/CD configuration
files:documentationRelative path(*) to the documentation file
files:changelogRelative path(*) to the changelog file
data:descriptionThe template description
data:iconIcon of the template (see emoji list)📋
data:labelsList of template labels (see list of available labels below)[]
data:licenseThe template license
data:deprecatedSet the template as deprecatedfalse
Template visibility

The visibility of a template is the same than the visibility of its repository

(*) Relative path

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

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

🛠️ 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

Template versioning rely on source repository git tags. 2 options are supported in R2Devops:

  1. Tags scoped to all templates of the repository, without prefix. Ex: 1.2.3
  2. Tags scoped to only one template, prefixed with its path. Ex: docker_build@1.2.3
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.md
# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [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
Example of CHANGELOG.md fully compliant to Keep a Changelog standard
# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.4.0] - Unreleased

### Added

- Add new option `--use-new-run` to kaniko executor (enabled by default)

### Changed

- Update kaniko image to `v1.5.1`

## [0.3.0] - 2023-11-25

### Added

- 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

### Added

- Add variable `DOCKERFILE_PATH` which permits specifying custom path to
Dockerfile

## [0.1.0] - 2023-10-21

- Initial version