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
- Create a GitLab repository
- In this repository:
- Create R2 file
- Create CI/CD configuration
- (optional) Create documentation file
- (optional) Setup versioning
- (optional) Create changelog file
- Login on R2Devops
- In "Import templates" page: import your repository
🔄 Update a catalog¶
- Update your template(s) in the GitLab repository
- Create new version tag
- Login on R2Devops
- In "Import templates" page: click on refresh button
❌ Delete a catalog¶
- Login on R2Devops
- 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: 🐳
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
- API
- Artisan
- 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:
- GitLab CI/CD pipeline configuration reference
- R2Devops guidelines and best practices about job definition.
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:
- Tags scoped to all templates of the repository, without prefix. Ex:
1.2.3
- Tags scoped to only one template, prefixed with its path. Ex:
docker_build@1.2.3
Note
- The version
latest
is created using theHEAD
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