using components

Using GitLab CI/CD Components

This guide covers how to consume components in your pipelines.

Basic Usage

Referencing Components

Components are referenced using the include keyword with the component syntax:

# .gitlab-ci.yml
include:
  - component: gitlab.com/group/project/component-name@version
    inputs:
      input_name: value

Syntax Breakdown

component: gitlab.com/group/project/component-name@version
           
            Full component path

           gitlab.com             - GitLab instance (or self-managed URL)
                      group       - Group or namespace
                            project - Project name
                                    component-name - Component name
                                                   version - Version reference

Version Pinning Strategies

Production: Pin to Exact Version

Recommended for production pipelines:

include:
  - component: gitlab.com/my-org/components/deploy@1.2.3
    inputs:
      environment: production

Pros:

Predictable behavior
No unexpected changes
Audit trail for version changes

Cons:

Manual updates required
Can fall behind security patches

Development: Use Latest Patch

For non-critical environments:

include:
  - component: gitlab.com/my-org/components/deploy@~1.2
    inputs:
      environment: staging

This selects the latest 1.2.x version, automatically getting patch updates.

Experimental: Latest Version

For testing new versions:

include:
  - component: gitlab.com/my-org/components/deploy@~latest
    inputs:
      environment: development

Warning: Only use in development - never in production.

By Commit SHA

For testing unreleased changes:

include:
  - component: gitlab.com/my-org/components/deploy@e3262fdd091
    inputs:
      environment: preview

Use case: Testing component changes before release.

Version Strategy by Environment

# .gitlab-ci.yml

# Production - exact version
deploy-production:
  stage: deploy
  include:
    - component: gitlab.com/my-org/components/deploy@2.1.0
      inputs:
        environment: production
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# Staging - latest patch in series
deploy-staging:
  stage: deploy
  include:
    - component: gitlab.com/my-org/components/deploy@~2.1
      inputs:
        environment: staging
  rules:
    - if: $CI_COMMIT_BRANCH == "staging"

# Development - latest version
deploy-dev:
  stage: deploy
  include:
    - component: gitlab.com/my-org/components/deploy@~latest
      inputs:
        environment: development
  rules:
    - if: $CI_MERGE_REQUEST_IID

Providing Inputs

String Inputs

include:
  - component: gitlab.com/my-org/components/docker-build@1.0.0
    inputs:
      image_name: 'myapp:latest'
      dockerfile: 'docker/Dockerfile'

Boolean Inputs

include:
  - component: gitlab.com/my-org/components/node-pipeline@2.0.0
    inputs:
      enable_lint: true
      enable_tests: false

Number Inputs

include:
  - component: gitlab.com/my-org/components/load-test@1.5.0
    inputs:
      timeout: 300
      parallel: 4

Array Inputs

include:
  - component: gitlab.com/my-org/components/deploy@3.0.0
    inputs:
      environments: ['staging', 'production']
      regions: ['us-east-1', 'eu-west-1']

Using CI/CD Variables in Inputs

include:
  - component: gitlab.com/my-org/components/deploy@1.0.0
    inputs:
      environment: $CI_ENVIRONMENT_NAME
      version: $CI_COMMIT_TAG
      image_name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

Multiple Components

Sequential Components

include:
  # Build component
  - component: gitlab.com/my-org/components/docker-build@1.0.0
    inputs:
      image_name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

  # Test component
  - component: gitlab.com/my-org/components/security-scan@2.0.0
    inputs:
      image: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

  # Deploy component
  - component: gitlab.com/my-org/components/k8s-deploy@3.0.0
    inputs:
      image: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
      environment: production

Conditional Components

include:
  # Always include build
  - component: gitlab.com/my-org/components/build@1.0.0

  # Include security scan only on main branch
  - component: gitlab.com/my-org/components/security-scan@2.0.0
    rules:
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  # Include deploy only on tags
  - component: gitlab.com/my-org/components/deploy@3.0.0
    rules:
      - if: $CI_COMMIT_TAG

Combining Components with Local Configuration

Adding Custom Jobs

# Use component for standard pipeline
include:
  - component: gitlab.com/my-org/components/node-pipeline@2.0.0
    inputs:
      node_version: '20'

# Add project-specific job
custom-integration-test:
  stage: test
  image: node:20
  script:
    - npm run test:integration
  services:
    - postgres:15

Extending Component Jobs

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

# Extend the component's build job
build-docker-image:
  before_script:
    - echo "Custom pre-build steps"
    - setup-buildx.sh
  after_script:
    - echo "Custom post-build steps"
    - notify-slack.sh

Overriding Component Behavior

include:
  - component: gitlab.com/my-org/components/deploy@1.0.0

# Override specific job from component
deploy-job:
  variables:
    CUSTOM_VAR: "override-value"
  environment:
    name: production
    url: https://app.example.com

Discovering Components

GitLab CI/CD Catalog

Navigate to your GitLab instance:

Go to Main Menu † Explore
Click CI/CD Catalog
Search for components by:
- Component name
- Description
- Tags
- Project namespace

Viewing Component Details

Click on a component to view:

README: Component documentation
Versions: All published versions
Usage examples: How to use the component
Inputs: Available input parameters

Component Search Tips

By functionality:

docker build deploy

By technology:

kubernetes helm terraform

By organization:

Filter by: my-organization/*

Debugging Component Issues

Check Component Version

# Add debug job to verify component version
debug-components:
  stage: .pre
  script:
    - echo "Component versions in use:"
    - cat .gitlab-ci.yml | grep 'component:'

Validate Inputs

Component inputs are validated at pipeline creation time. Check pipeline errors for:

Invalid input type: expected string, got number
Missing required input: environment
Input value not in allowed options: ['dev', 'staging', 'prod']
Input does not match regex: ^\d+\.\d+\.\d+$

View Resolved Configuration

Use the GitLab UI to see the fully resolved pipeline configuration:

Go to CI/CD † Pipelines
Click on a pipeline
Click View full configuration
See how components expanded into jobs

Common Errors

Component Not Found

Component not found: gitlab.com/group/project/component@1.0.0

Solutions:

Check project path spelling
Verify component name exists in templates/
Ensure version/tag exists
Check project visibility (public/internal/private)

Invalid Version Reference

Invalid version: 1.0

Solution: Use proper semantic versioning:

component: gitlab.com/group/project/comp@1.0.0  # Not 1.0

Input Validation Failed

Input 'environment' must be one of: dev, staging, prod

Solution: Check component documentation for allowed input values.

Circular Dependency

Circular dependency detected in included components

Solution: Component A includes B, which includes A. Refactor to break cycle.

Performance Considerations

Component Loading Time

Components are fetched and resolved at pipeline creation time. For faster pipelines:

Minimize component count: Combine related functionality
Use local includes for frequently changed configs
Cache component definitions (handled by GitLab automatically)

Pipeline Creation Time

# Slower - many small components
include:
  - component: gitlab.com/org/comp/install@1.0.0
  - component: gitlab.com/org/comp/lint@1.0.0
  - component: gitlab.com/org/comp/test@1.0.0
  - component: gitlab.com/org/comp/build@1.0.0
  - component: gitlab.com/org/comp/deploy@1.0.0

# Faster - one comprehensive component
include:
  - component: gitlab.com/org/comp/full-pipeline@1.0.0
    inputs:
      enable_lint: true
      enable_tests: true

Migration from Templates

Before: Using Templates

# Old approach with templates
include:
  - project: my-org/ci-templates
    ref: main
    file: /templates/docker-build.yml

variables:
  IMAGE_NAME: myapp:latest
  DOCKERFILE: Dockerfile

After: Using Components

# New approach with components
include:
  - component: gitlab.com/my-org/components/docker-build@1.0.0
    inputs:
      image_name: myapp:latest
      dockerfile: Dockerfile

Migration Benefits

Type safety: Inputs validated at pipeline creation
Versioning: Semantic versions instead of git refs
Discoverability: Catalog instead of manual project URLs
Documentation: Embedded in catalog
Testing: Release pipeline ensures quality

Migration Steps

Identify template usage across projects
Create component in central project
Test component with representative projects
Release v1.0.0 to catalog
Update projects gradually
Deprecate old templates after migration period

Best Practices

1. Pin Production Versions

# Good - explicit version
component: gitlab.com/org/comp/deploy@2.1.5

# Bad - moving target
component: gitlab.com/org/comp/deploy@~latest

2. Document Component Usage

# .gitlab-ci.yml
# Component: gitlab.com/my-org/components/docker-build@1.0.0
# Purpose: Builds and pushes Docker images
# Docs: https://gitlab.com/my-org/components/-/blob/main/README.md#docker-build
include:
  - component: gitlab.com/my-org/components/docker-build@1.0.0
    inputs:
      image_name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

3. Use Consistent Input Patterns

# Good - use CI variables
include:
  - component: gitlab.com/org/comp/deploy@1.0.0
    inputs:
      environment: $CI_ENVIRONMENT_NAME
      version: $CI_COMMIT_TAG

# Bad - hardcoded values
include:
  - component: gitlab.com/org/comp/deploy@1.0.0
    inputs:
      environment: "production"
      version: "1.2.3"

4. Leverage Input Validation

Component maintainers define input constraints. Trust them:

# Component validates these constraints:
# - environment must be one of: dev, staging, prod
# - replicas must be between 1-10
# - version must match semantic versioning
include:
  - component: gitlab.com/org/comp/deploy@1.0.0
    inputs:
      environment: production  # Validated
      replicas: 5             # Validated
      version: 1.2.3          # Validated

5. Test Component Updates

Before updating component versions in production:

# Test branch - try new version
include:
  - component: gitlab.com/org/comp/deploy@2.0.0  # New version
    inputs:
      environment: staging

# After validation, update production
include:
  - component: gitlab.com/org/comp/deploy@2.0.0
    inputs:
      environment: production

Advanced Usage

Dynamic Component Selection

# Select component version based on environment
include:
  - component: gitlab.com/org/comp/deploy@$COMPONENT_VERSION
    inputs:
      environment: $CI_ENVIRONMENT_NAME

variables:
  COMPONENT_VERSION:
    value: "1.0.0"
    description: "Deploy component version"

Conditional Component Inputs

include:
  - component: gitlab.com/org/comp/deploy@1.0.0
    inputs:
      environment: $CI_ENVIRONMENT_NAME
      enable_rollback: $ENABLE_ROLLBACK
      enable_smoke_tests: $ENABLE_SMOKE_TESTS

variables:
  ENABLE_ROLLBACK: "true"
  ENABLE_SMOKE_TESTS:
    value: "true"
    options:
      - "true"
      - "false"

Component Composition Pattern

# Base pipeline from component
include:
  - component: gitlab.com/org/comp/base-pipeline@1.0.0

# Override or extend specific stages
include:
  - component: gitlab.com/org/comp/security-enhanced@1.0.0
    inputs:
      scan_type: comprehensive

# Add deployment
include:
  - component: gitlab.com/org/comp/k8s-deploy@2.0.0
    inputs:
      cluster: production

Troubleshooting Checklist

Component path is correct
Version exists and is published
Required inputs are provided
Input types match component definition
Input values pass validation (options, regex)
Project has access to component project
Component version is available in catalog
No circular dependencies between components

Next Steps

Multi-Project Strategy: Roll out components to 70+ projects
Versioning: Understand version update strategies
Governance: Change management and approval processes
Patterns: Common component usage patterns