Working with CI/CD Components and Catalog
1. Creating Reusable Components
Example: Define a reusable component in a YAML file
include:
local: "components/deploy.yaml"
variables:
ENVIRONMENT: "staging"
| Component Type | Description | Usage |
|---|---|---|
| Template | Reusable configuration defined in a YAML file | Include in job definitions using include |
| Component | Predefined set of configuration options and values | Used to standardize workflows across projects |
| Pipeline | Complete CI/CD process defined in a YAML file | Can be included or referenced in other pipelines |
Note: Components must be defined in a
.gitlab-ci.yml or included from another file using the include keyword.Warning: Reusable components are not supported in GitLab Free tier.
Key Features of Reusable Components
- Templates can be shared across multiple projects
- Components simplify pipeline configuration by reducing duplication
- Supports variables and conditional logic
2. Publishing to CI/CD Catalog
Example: Publishing a Pipeline Template
publish_to_catalog:
stage: deploy
script:
- echo "Publishing pipeline template to catalog"
- git config --global user.name "GitLab CI"
- git config --global user.email "ci@gitlab.com"
- git add .
- git commit -m "Publish pipeline template"
- git push origin main
only:
- main
| Field | Description | Values |
|---|---|---|
| publish_to_catalog | Job name for publishing to CI/CD Catalog | publish_to_catalog |
| stage | Execution stage for the job | deploy |
| script | Commands to execute during publishing | Array of shell commands |
| only | Branches or tags to run the job on | main |
Note: Ensure that the job has appropriate permissions to push to the catalog repository.
Warning: The catalog requires a valid
.gitlab-ci.yml file to be present in the root directory.Key Steps for Publishing
- Create a new job in your
.gitlab-ci.ymlfile - Define the job to run on a specific branch (e.g.,
main) - Include commands to commit and push changes to the catalog repository
- Ensure proper Git configuration for user name and email
3. Using Component Inputs
| Input | Description | Type | Required |
|---|---|---|---|
| component | Name of the component to use | string |
Yes |
| version | Version of the component to use | string |
No |
| inputs | Map of input values to pass to the component | object |
No |
Example: Using Component Inputs
job:
trigger:
component: "my-component"
version: "1.0.0"
inputs:
environment: "production"
timeout: "30s"
Note: Component inputs are passed as environment variables to the component's job.
4. Versioning Components
| Version Type | Description | Examples | Notes |
|---|---|---|---|
| Major | Breaking changes that require updates to consumers | v1.0.0 |
Incremented when incompatible API changes are made |
| Minor | Backward-compatible features added | v1.2.0 |
Used for new functionality without breaking changes |
| Patch | Backward-compatible bug fixes | v1.2.3 |
For minor fixes that don't change functionality |
| Pre-release | Alpha, beta, or release candidate versions | v1.2.3-alpha.1 |
Indicates unstable or experimental builds |
| Build Metadata | Additional information about build environment | v1.2.3+build.123 |
Used to track build-specific details like commit hash |
Example: Versioning in GitLab CI
variables:
PACKAGE_VERSION: "1.2.3"
before_script:
- echo "Building version $PACKAGE_VERSION"
Note: GitLab CI does not enforce semantic versioning but supports it through variables and tagging strategies.
5. Including Catalog Components
GitLab CI/CD allows you to include reusable components from the GitLab CI/CD Catalog directly into your projects. These components are pre-built templates that can be customized to fit your project's needs.
| Component | Description | Usage | Version |
|---|---|---|---|
| Docker Build | Builds a Docker image using a provided Dockerfile. | include: with a reference to the component |
v1.0 |
| Node.js Test | Runs tests for a Node.js project using npm or yarn. | include: with component path |
v2.1 |
| Deploy to Kubernetes | Deploys an application to a Kubernetes cluster using Helm. | include: with namespace and chart details |
v3.0 |
Note: The
component key must point to a valid catalog component. Ensure the component is accessible in your GitLab instance.
Warning: Including components from external sources may introduce security risks. Always validate and review the component before including it in your pipeline.
6. Creating Component Templates
| Field | Description | Example |
|---|---|---|
| template_name | Name of the component template | frontend-template |
| description | Short description of the template | A reusable frontend component template |
| category | Category for grouping templates | frontend |
| version | Version of the template (e.g., v1.0.0) |
v1.0.0 |
| variables | Variables that can be overridden in component instances | {"node_version": "18"} |
Example: Component Template YAML
template_name: "frontend-template"
description: "A reusable frontend component template"
category: "frontend"
version: "v1.0.0"
variables:
node_version: "18"
build_command: "npm run build"
Note: Component templates must be stored in a GitLab project with the
.gitlab/component-template.yaml file.
Warning: Templates must not contain sensitive data or secrets. Use variables for configuration.
Best Practices
- Use descriptive names and categories for templates
- Define variables to allow customization in component instances
- Version templates to support backward compatibility
- Store templates in a dedicated project or namespace
7. Using Component Outputs
| Property | Description | Usage |
|---|---|---|
| artifacts | Defines files or directories to be stored and passed between jobs | artifacts: section in job configuration |
| reports | Defines reports to be generated and stored (e.g., test results, security scans) | reports: section in job configuration |
| dependencies | Specifies which jobs to download artifacts from | dependencies: in job configuration |
Example: Using Artifacts to Pass Data Between Jobs
build_job:
stage: build
script:
- echo "Building project..."
- mkdir -p dist
- echo "build output" > dist/output.txt
artifacts:
paths:
- dist/
test_job:
stage: test
script:
- echo "Running tests..."
- cat dist/output.txt
dependencies:
- build_jobExample: Using Reports to Store Test Results
test_job:
stage: test
script:
- npm run test -- --reporter=junit
reports:
junit: tests.xml
Note: Artifacts and reports are stored in GitLab and can be downloaded from the UI or API. Artifacts are retained for a configurable period.
8. Implementing Component Testing
| Aspect | Description | Notes |
|---|---|---|
| Test Configuration | test: job in .gitlab-ci.yml |
Defines how tests are run in the pipeline |
| Test Framework | Supports Jest, Mocha, Cypress, etc. | Configurable via package.json scripts |
| Test Reporting | JUnit XML output for test results | Used by GitLab to display test coverage and failures |
Example: Running Jest Tests in GitLab CI
test:
stage: test
script:
- npm install
- npm run test:ci
artifacts:
reports:
junit: junit.xml
Example: Running Cypress Tests
test:e2e:
stage: test
script:
- npm install
- npx cypress run --reporter junit --reporter-options "output=junit.xml"
artifacts:
reports:
junit: junit.xml
Note: Ensure that test artifacts are properly configured to report results back to GitLab for visibility in the pipeline UI.
9. Documenting Components
| Field | Description | Example |
|---|---|---|
| title | Title of the component | "My Component" |
| description | Short description of the component | "A reusable CI/CD component for deployment" |
| icon | URL or path to an icon image | "https://example.com/icon.png" |
| category | Category for grouping components | "deployment" |
| maintainer | Person or team responsible for the component | "DevOps Team" |
| version | Version of the component | "v1.2.0" |
| tags | List of tags for searchability | ["ci", "cd", "deployment"] |
| documentation | URL to detailed documentation | "https://docs.example.com/component" |
Example: Component Metadata File
title: "My Deployment Component"
description: "A reusable CI/CD component for deploying applications to Kubernetes"
icon: "https://example.com/deploy-icon.png"
category: "deployment"
maintainer: "DevOps Team"
version: "v1.2.0"
tags:
- "ci"
- "cd"
- "kubernetes"
documentation: "https://docs.example.com/deployment-component"
Note: Component documentation should include usage instructions, configuration options, and examples.
Best Practices for Component Documentation
- Include clear, concise descriptions for each field
- Use consistent formatting across all components
- Provide real-world examples where applicable
- Keep documentation up-to-date with component changes
10. Managing Component Dependencies
| Dependency Type | Description | Management Method | Notes |
|---|---|---|---|
| Project Dependencies | Dependencies required for a project's build and runtime | .gitlab-ci.yml with before_script or script |
Can be managed via package managers like npm, pip, or Maven |
| Component Dependencies | Dependencies between components in a CI/CD catalog | Defined in component gitlab-ci.yml or catalog.json |
Used to ensure proper order and availability of components in pipelines |
| External Dependencies | Dependencies from external sources or services | Configured via variables or secrets |
May require authentication tokens or API keys to access |
Example: Defining Component Dependencies in CI/CD
components:
- name: frontend
dependencies:
- name: backend
version: v1.0.0
- name: backend
dependencies:
- name: database
version: v2.0.0
Note: Component dependencies are managed through the GitLab CI/CD catalog and can be defined in
catalog.json or within individual component configurations.
Warning: Ensure that all dependencies are compatible with the component's runtime environment to avoid pipeline failures.