Skip to main content

README

GitLab CI/CD Components Documentation

Comprehensive guide to GitLab CI/CD Components for managing pipelines across 70+ projects in the Agent Platform.

Overview

GitLab CI/CD Components are reusable, versioned pipeline configurations that enable:

  • Centralized Management: Single source of truth for shared CI/CD logic
  • Version Control: Semantic versioning for predictable updates
  • Type Safety: Validated inputs prevent configuration errors
  • Discoverability: CI/CD Catalog for finding and sharing components
  • Scale: Efficiently manage 70+ projects with consistent pipelines

Documentation Structure

1. [object Object]

Start here to understand components.

Topics covered:

  • What are CI/CD Components?
  • Component vs. Template comparison
  • Component anatomy and structure
  • Version references
  • Component catalog
  • Multi-project strategy benefits

Time to read: 15 minutes

2. [object Object]

Learn how to build reusable components.

Topics covered:

  • Project structure and required files
  • Component definition with inputs
  • Input types and validation
  • Conditional inputs with rules
  • Component documentation
  • Testing components
  • Component composition
  • Common pitfalls and best practices

Time to read: 45 minutes

3. [object Object]

Learn how to consume components in pipelines.

Topics covered:

  • Referencing components
  • Version pinning strategies
  • Providing inputs
  • Multiple components
  • Combining with local configuration
  • Discovering components in catalog
  • Debugging component issues
  • Performance considerations
  • Migration from templates

Time to read: 30 minutes

4. [object Object]

Critical for managing 70+ projects.

Topics covered:

  • Centralized component repository pattern
  • Component organization strategies
  • Version management (stable, current, preview, deprecated)
  • Rollout process (development † beta † stable † gradual rollout)
  • Automation tools
  • Communication strategy
  • Handling breaking changes
  • Testing multi-project changes
  • Monitoring and metrics
  • Rollback strategy

Time to read: 60 minutes

5. [object Object]

Understand semantic versioning for components.

Topics covered:

  • Semantic versioning (MAJOR.MINOR.PATCH)
  • Version references (exact, partial, latest, SHA)
  • Version strategy by environment
  • Version lifecycle (development † stable † maintenance † deprecated † EOL)
  • Version support policy
  • CHANGELOG.md and migration guides
  • Automated version management (semantic-release)
  • Version compliance and enforcement

Time to read: 45 minutes

6. [object Object]

Change management and approval processes.

Topics covered:

  • Governance model and stakeholders
  • Change classification (patch, minor, major, security)
  • Approval processes for each change type
  • Request for Comments (RFC) template
  • Change request workflow
  • Communication standards
  • Deprecation policy
  • Metrics and reporting

Time to read: 60 minutes

7. [object Object]

Common design patterns for components.

Topics covered:

  • Job template patterns
  • Workflow template patterns
  • Composition patterns
  • Extension patterns (hooks, strategy)
  • Multi-environment patterns
  • Security patterns
  • Performance patterns
  • Notification patterns
  • Anti-patterns to avoid

Time to read: 45 minutes

8. [object Object]

Comprehensive testing strategies.

Topics covered:

  • Testing levels (syntax, unit, integration, E2E, acceptance)
  • Syntax validation
  • Unit testing components
  • Integration testing with test projects
  • Test coverage matrix
  • Beta testing process
  • Regression testing
  • Performance testing
  • Continuous testing
  • Test automation

Time to read: 45 minutes

Quick Start

For Component Creators

  1. Read Overview to understand concepts
  2. Follow Creating Components to build your first component
  3. Review Patterns for design guidance
  4. Implement Testing strategies

For Component Consumers

  1. Read Overview to understand concepts
  2. Follow Using Components to consume components
  3. Review version pinning in Versioning
  4. Understand debugging in Using Components

For Platform Team

  1. Read Multi-Project Strategy for 70+ project management
  2. Study Governance for change management
  3. Review Versioning for support policy
  4. Implement Testing automation

Key Concepts

Component

A reusable, single-purpose pipeline configuration unit with:

  • Typed inputs for configuration
  • Semantic versioning
  • Published to CI/CD Catalog

Component Catalog

Central registry where components are:

  • Discovered by teams
  • Versioned and documented
  • Tracked for usage

Semantic Versioning

Version format: MAJOR.MINOR.PATCH

  • MAJOR: Breaking changes
  • MINOR: New backward-compatible features
  • PATCH: Backward-compatible bug fixes

Component Repository

Central project containing all shared components for 70+ projects:

gitlab_components/
 templates/
‚    docker-build.yml
‚    k8s-deploy.yml
‚    security-scan.yml
‚    node-pipeline.yml
 tests/
 README.md
 .gitlab-ci.yml

Common Workflows

Creating a New Component

  1. Create component file in templates/
  2. Define spec:inputs for configuration
  3. Write component jobs
  4. Create tests
  5. Submit MR for review
  6. Tag and release version

Guide: Creating Components

Updating a Component

  1. Determine change type (patch/minor/major)
  2. Follow appropriate approval process
  3. Update tests
  4. Create beta release
  5. Test with real projects
  6. Release stable version
  7. Communicate to users

Guide: Governance

Rolling Out to 70+ Projects

  1. Test internally (alpha)
  2. Beta test with 5-10 projects (2 weeks)
  3. Release stable version
  4. Gradual rollout by tiers (12 weeks)
  5. Monitor metrics
  6. Deprecate old version

Guide: Multi-Project Strategy

Handling Breaking Changes

  1. Create RFC with migration plan
  2. Get stakeholder approval
  3. Announce 4+ weeks early
  4. Provide migration guide
  5. Release with major version bump
  6. Support migration (12+ weeks)
  7. Deprecate old version (90 days)
  8. EOL after deprecation period

Guide: Governance

Component Examples

Simple Docker Build

# templates/docker-build.yml
spec:
  inputs:
    image_name:
      type: string
    dockerfile:
      type: string
      default: 'Dockerfile'

---

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $[[ inputs.image_name ]] -f $[[ inputs.dockerfile ]] .
    - docker push $[[ inputs.image_name ]]

Usage:

include:
  - component: gitlab.com/org/comp/docker-build@1.0.0
    inputs:
      image_name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

Complete Node.js Pipeline

# templates/node-pipeline.yml
spec:
  inputs:
    node_version:
      type: string
      default: '20'
    enable_tests:
      type: boolean
      default: true

---

stages:
  - build
  - test

install:
  stage: build
  image: node:$[[ inputs.node_version ]]
  script:
    - npm ci

test:
  stage: test
  image: node:$[[ inputs.node_version ]]
  script:
    - npm test
  rules:
    - if: $[[ inputs.enable_tests ]]

Usage:

include:
  - component: gitlab.com/org/comp/node-pipeline@2.0.0
    inputs:
      node_version: '18'
      enable_tests: true

Tools and Resources

Component Development

  • Validation: yq, yamllint
  • Testing: GitLab CI, test projects
  • Versioning: semantic-release
  • Documentation: Markdown, GitLab Wiki

Component Management

  • Catalog: GitLab CI/CD Catalog
  • CLI: glab for GitLab operations
  • Monitoring: GitLab Analytics, custom dashboards
  • Communication: Slack, email, GitLab issues

Helpful Links

Success Metrics

Track these metrics for component health:

  • Adoption Rate: % of projects using latest version
  • Update Velocity: Average days to upgrade
  • Pipeline Success Rate: % successful pipelines
  • Rollback Rate: % projects rolling back
  • Test Coverage: % of inputs and scenarios tested
  • User Satisfaction: Feedback ratings

Target Metrics:

  • 90%+ adoption within 12 weeks
  • <5% pipeline failure rate
  • <2% rollback rate
  • 80%+ test coverage
  • 4+/5 user satisfaction

Getting Help

Questions?

Support

  • Component Issues: File issue in component repository
  • Migration Help: Contact @platform-team
  • Security Concerns: Contact @security-team
  • Approval Questions: See Governance

Contributing

Contributions to components welcome!

  1. Fork component repository
  2. Create feature branch
  3. Make changes with tests
  4. Submit MR with clear description
  5. Address review feedback
  6. Celebrate merge!

See Governance for approval process.

Changelog

  • 2026-01-08: Initial documentation created
  • Components guide for 70+ project management
  • Covers creation, usage, strategy, governance

License

Documentation licensed under CC BY-SA 4.0

Components follow project-specific licenses.

Next Steps

New to components? † Start with Overview

Building components? † Read Creating Components

Using components? † Read Using Components

Managing 70+ projects? † Read Multi-Project Strategy

Need governance info? † Read Governance