`apiVersion` v2

Overview

apiVersion v2 extends v1 with project metadata support. In addition to managing files, CI/CD variables and webhooks, a v2 Gear synchronizes the description, icon and CI/CD catalog of the GitLab project it is installed into.

Warning

v2 is a strict superset of v1. Sections added in v2 (description, icon, subtype) are not accepted in a v1 package.yaml and will be rejected as extra sections.

Gear file structure

The structure is the same as in v1 (including the optional files/ directories for static files).

Description `package.yaml` file sections

Section	Description	Available types	Example
`apiVersion`	`package.yaml` API version for git-system-follower to understand how to work with this Gear	`v2`	`v2`
`type`	Gear type	`gitlab-ci-pipeline`	`gitlab-ci-pipeline`
`name`	Gear name	`any`	`my-first-gear`
`version`	Gear version	`any`	`1.0.0`
`dependencies`	List of dependencies specified as Docker images	`any`	`artifactory.company.com/path-to/your-image:1.0.0`
`description`	Project description that will be synchronized to GitLab	`any`	`My first gear`
`icon`	Path to the project icon file inside the `scripts/` directory that will be uploaded to GitLab	`any`	`icon.png`
`subtype`	Gear subtype	`component`	`component`

Differences from v1

description (new, optional): used as the GitLab project description.
icon (new, optional): relative path (inside scripts/) to an image file which is uploaded as the GitLab project avatar.
subtype (new, optional): narrows down the Gear type. Currently the only supported value is component.

Example

With dependency and subtype

apiVersion: v2
type: gitlab-ci-pipeline
name: my-gear
version: 1.0.0
description: 'CI/CD pipeline for my service'
icon: 'icon.png'
subtype: component
dependencies:
  - artifactory.company.com/path-to/my-another-image:1.0.0

Without dependencies

apiVersion: v2
type: gitlab-ci-pipeline
name: my-gear
version: 1.0.0
description: 'CI/CD pipeline for my service'
icon: 'icon.png'

Project metadata synchronization

When description and icon are present in package.yaml, git-system-follower automatically synchronizes the following project attributes with GitLab during install and update:

Project description – set from the description section.
Project icon (avatar) – uploaded from the file referenced by icon (resolved relative to the scripts/ directory of the executed version).
CI/CD catalog – enabled/disabled by passing the --extra gitlab_cicd_project_catalog <true|false> <masked|no-masked> extra parameter.

The metadata is tracked in the .state.yaml file in the project_metadata section and validated on subsequent runs. If the project description or icon was modified externally, git-system-follower fails with an error. Each field can be demoted to a warning independently with the --skip-project-description and --skip-project-icon flags of the install and uninstall commands. See Project Metadata Skip Flags for the full behavior, including v1 to v2 migration scenarios.

project_metadata:
  description: 'CI/CD pipeline for my service'
  icon: 'icon.png'
  icon_hash: '<sha256 hash of the icon file>'
  cicd_catalog: false

Develop API

Gear scripts should import the package API from the versioned v2 surface:

from git_system_follower.develop.api.v2.types import Parameters
from git_system_follower.develop.api.v2.cicd_variables import create_variable
from git_system_follower.develop.api.v2.templates import create_template, update_template, delete_template
from git_system_follower.develop.api.v2.webhooks import create_webhook

The v2 template functions (create_template, update_template) additionally trigger the project metadata synchronization described above.

For backwards compatibility the unversioned git_system_follower.develop.api import continues to work, but new Gears are recommended to use the versioned surface.

apiVersion v2