Skip to main content

overview

GitLab CI/CD Components - Overview

What Are CI/CD Components?

A CI/CD component is a reusable single pipeline configuration unit that can be used to create a small part of a larger pipeline, or even to compose a complete pipeline configuration. Components are the modern replacement for GitLab CI/CD templates, designed with deterministic behavior and reusability in mind.

Key Characteristics

  • Single-purpose building blocks that abstract away pipeline configuration units
  • Versioned and immutable when published to the CI/CD Catalog
  • Typed inputs with built-in validation at pipeline creation time
  • Catalog-discoverable for sharing across projects and groups

Why Components?

Components solve several problems with traditional CI/CD templates:

  1. Deterministic behavior: Version pinning ensures consistent behavior across projects
  2. Type safety: Input validation prevents configuration errors
  3. Discoverability: Central catalog makes components easy to find and reuse
  4. Maintainability: Update once, roll out across all consuming projects
  5. Testing: Components can be tested before release

Component vs. Template

FeatureTraditional TemplatesCI/CD Components
VersioningGit refs (branches, commits)Semantic versions (tags)
DiscoveryManual (project URLs)CI/CD Catalog
InputsCI/CD variablesTyped spec:inputs
ValidationRuntimePipeline creation time
ReusabilityInclude from projectsCatalog references
TestingManualTag pipeline testing

Component Anatomy

Basic Structure

# templates/my-component.yml
spec:
  inputs:
    environment:
      type: string
      default: 'staging'
    debug:
      type: boolean
      default: false

---

deploy-job:
  stage: deploy
  script:
    - echo "Deploying to $[[ inputs.environment ]]"
    - if [ "$[[ inputs.debug ]]" = "true" ]; then set -x; fi
    - ./deploy.sh
  environment:
    name: $[[ inputs.environment ]]

Component Reference

# Consuming project's .gitlab-ci.yml
include:
  - component: gitlab.com/my-group/my-components/my-component@1.0.0
    inputs:
      environment: production
      debug: true

Component Types

1. Job Templates

Single reusable jobs with configurable inputs:

# templates/security-scan.yml
spec:
  inputs:
    scan_type:
      type: string
      options: ['sast', 'dast', 'dependency']

---

security-scan:
  stage: test
  script:
    - run-$[[ inputs.scan_type ]]-scan

2. Workflow Templates

Complete pipeline configurations:

# templates/full-pipeline.yml
spec:
  inputs:
    enable_tests:
      type: boolean
      default: true

---

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script: make build

test-job:
  stage: test
  script: make test
  rules:
    - if: $[[ inputs.enable_tests ]]

3. Utility Components

Reusable script fragments or configuration:

# templates/notification.yml
spec:
  inputs:
    webhook_url:
      type: string
    message:
      type: string

---

notify:
  stage: .pre
  script:
    - 'curl -X POST $[[ inputs.webhook_url ]] -d "message=$[[ inputs.message ]]"'

Version References

Components can be referenced using several formats:

Semantic Version (Recommended)

component: gitlab.com/group/project/component@1.0.0

Partial Version (Latest Match)

component: gitlab.com/group/project/component@~1.0  # Latest 1.0.x
component: gitlab.com/group/project/component@~1    # Latest 1.x.x
component: gitlab.com/group/project/component@~latest  # Latest version

Commit SHA (Not Recommended)

component: gitlab.com/group/project/component@e3262fdd0914fa823210cdb79a8c421e2cef79d8

Best Practice: Pin to semantic versions for production, use ~latest only for development.

Component Limits

  • Maximum 100 components per project (increased from 30 in GitLab 18.5)
  • Components must be in templates/ directory
  • Each component requires either:
    • templates/component-name.yml (single file)
    • templates/component-name/template.yml (directory with subdirectory)

Component Catalog

The CI/CD Catalog is the central discovery mechanism for components.

Catalog Requirements

To publish to the catalog, a project must:

  1. Be marked as a Catalog Resource
  2. Have a project description
  3. Contain a README.md in the root
  4. Have at least one component in templates/
  5. Use semantic versioning for releases

Catalog Benefits

  • Searchable: Find components by name, description, tags
  • Versioned: See all available versions
  • Documented: README and component descriptions visible
  • Usage stats: Track which projects use your components

Multi-Project Strategy

For organizations managing many projects (like 70+), components provide:

  1. Centralized updates: Change once, roll out everywhere
  2. Version control: Gradual migration across projects
  3. Standards enforcement: Ensure all projects follow best practices
  4. Reduced duplication: Single source of truth for common patterns

Quick Start Example

1. Create Component Project

# Create new project for components
glab repo create my-components --public

cd my-components
mkdir templates

2. Define Component

# templates/build-go.yml
spec:
  inputs:
    go_version:
      type: string
      default: '1.21'

---

build:
  image: golang:$[[ inputs.go_version ]]
  stage: build
  script:
    - go build -o app
  artifacts:
    paths:
      - app

3. Publish Component

# .gitlab-ci.yml
release:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - echo "Creating release $CI_COMMIT_TAG"
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release $CI_COMMIT_TAG'
# Tag and push
git tag 1.0.0
git push origin 1.0.0

4. Use Component

# Another project's .gitlab-ci.yml
include:
  - component: gitlab.com/my-group/my-components/build-go@1.0.0
    inputs:
      go_version: '1.22'

Next Steps

References