Build Gear (v2)

How to build your project as a Gear with apiVersion: v2.

v2 is a strict superset of v1. Building and publishing is the same as for v1 — only the package.yaml file has additional sections.

Docker image with artifact

Dockerfile file

This simply requires you to put the gear in the image:

FROM scratch

LABEL gsf.package="true"

COPY git-system-follower-package /git-system-follower-package

Build & publish your Gear:

docker build -t <image>:<tag> .
docker push <registry>/<image>:<tag>

For details about when the gsf.package label is required, see Image Labels.

OCI artifact

Recommended option when you build your Gear as an OCI artifact.

Publish your Gear:

oras push <your registry> git-system-follower-package/

Package file structure

<your repository>
├─ git-system-follower-package/
│  ├─ package.yaml
│  └─ scripts/
│     └─ ...
└─ <your other files>

The scripts/ directory may contain cookiecutter templates/ directories and/or files/ directories for static files. See Gear structure types and Static files for the full layout.

package.yaml

Example:

apiVersion: v2
type: gitlab-ci-pipeline
name: my-first-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

v2-only sections

Section	Description
description	Project description that will be synchronized to GitLab
icon	Path to the project icon file inside the scripts/ directory
subtype	Gear subtype, currently the only supported value is component

For the full description of the v2 package.yaml sections, see apiVersion v2.

Project metadata synchronization

When description and icon are present in package.yaml, git-system-follower automatically synchronizes the project description, icon and CI/CD catalog with GitLab during install and update. The metadata is tracked in the .state.yaml file. See apiVersion v2 for details.

Develop API

v2 package scripts import the package API from the v2 surface:

from git_system_follower.develop.api.v2 import Parameters, ProjectMetadata
from git_system_follower.develop.api.v2.templates import create_template

The v2 template functions (create_template, update_template) automatically trigger the project metadata synchronization. See the Develop Interface reference.