Use when creating reusable GitLab CI/CD configurations, building component catalog entries, or packaging pipeline templates for sharing - provides systematic guide following GitLab documentation to...
GitLab CI components are reusable pipeline configuration units that can be versioned, shared, and discovered through the CI/CD Catalog. This skill guides you through creating complete, correct components following GitLab's official structure.
Core principle: Follow the GitLab documentation systematically. Components have specific requirements for directory structure, files, inputs, and CI/CD configuration that must be met for valid components.
Use this skill when:
These are commonly missed - verify each one:
templates/ directory with components as .yml files or subdirectories with template.ymlspec:inputs syntax correct with proper types and validation$[[ inputs.field-name ]] in template--- separator present between spec and job definitions$CI_SERVER_FQDN and inputs instead of hardcoded domains/valuesmy-component/
├── templates/
│ └── my-component.yml # Component definition
├── README.md # Documentation with usage examples
├── LICENSE.md # Required license file
└── .gitlab-ci.yml # Testing and publishing
my-components/
├── templates/
│ ├── component-one.yml # Simple single-file component
│ ├── component-two/ # Multi-file component
│ │ ├── template.yml # Main template
│ │ └── supporting-script.sh # Supporting files
│ └── component-three.yml
├── README.md # Covers all components
├── LICENSE.md
└── .gitlab-ci.yml
Limits:
spec:
inputs:
stage:
type: string
default: test
description: "Pipeline stage for the job"
dockerfile_path:
type: string
default: Dockerfile
description: "Path to Dockerfile"
image_name:
type: string
description: "Docker image name (required)"
image_tag:
type: string
default: latest
description: "Docker image tag"
---
build-docker-image:
stage: $[[ inputs.stage ]]
image: docker:latest
script:
- docker build -f $[[ inputs.dockerfile_path ]] -t $[[ inputs.image_name ]]:$[[ inputs.image_tag ]] .
Key syntax:
spec:inputs: defines configurable parameters--- separator required between spec and jobs$[[ inputs.field-name ]] for referencing inputsdefault are requiredInput attributes:
type: Data type (string, number, boolean, array)default: Default value (makes input optional)description: Documents the input purposeValidation options:
type: Enforces data typeregex: Pattern validation (e.g., ^v\d+\.\d+(\.\d+)?$)options: Restricts to allowed values (e.g., ['dev', 'staging', 'prod'])Empty spec handling:
# If no inputs needed, use empty spec (not blank)
spec: {}
---
Complete input specification reference: https://docs.gitlab.com/ci/inputs/
# Test the component works correctly
test-component:
stage: test
trigger:
include:
- component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/my-component@$CI_COMMIT_SHA
inputs:
image_name: test-image
image_tag: test-tag
# Publish to catalog when a tag is created
release:
stage: deploy
image: registry.gitlab.com/gitlab-org/release-cli:latest
rules:
- if: $CI_COMMIT_TAG =~ /^\d+\.\d+\.\d+$/ # Semantic version tags only
script:
- echo "Releasing version $CI_COMMIT_TAG"
release:
tag_name: $CI_COMMIT_TAG
description: "Release $CI_COMMIT_TAG"
Versioning requirements:
1.0.0, 2.3.4, etc.1.2 matches latest 1.2.*~latest for absolute latest version (not recommended for production)# Component Name
Brief description of what the component does.
## Components
### component-name
Description of component functionality.
#### Inputs
| Input | Type | Default | Required | Description |
|-------|------|---------|----------|-------------|
| stage | string | test | No | Pipeline stage |
| image_name | string | - | Yes | Docker image name |
#### Usage
\`\`\`yaml
include:
- component: $CI_SERVER_FQDN/my-org/my-components/component-name@1.0.0
inputs:
image_name: myapp
image_tag: v1.2.3
\`\`\`
## Contributing
Guidelines for contributing to this component.
Required sections:
$CI_SERVER_FQDN (never hardcode domain)# ❌ BAD: Hardcoded values
script:
- curl https://gitlab.example.com/api/v4/projects
# ✅ GOOD: Use built-in variables
script:
- curl $CI_API_V4_URL/projects
Use predefined variables instead of hardcoded values:
$CI_SERVER_FQDN for domain names$CI_API_V4_URL for API referencesAll predefined variables: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
# ❌ BAD: Global default affects all jobs
default:
image: alpine:latest
# ✅ GOOD: Define reusable config with extends
.base-config:
image: alpine:latest
my-job:
extends: .base-config
Global keywords like default: affect the entire pipeline, not just your component.
include:
- component: <FQDN>/<project-path>/<component-name>@<version>
inputs:
field: value
Example:
include:
- component: $CI_SERVER_FQDN/my-org/security/secret-detection@1.0.0
inputs:
stage: security-scan
fail_on_detection: true
| Mistake | Consequence | Fix |
|---|---|---|
Missing templates/ directory |
Component not recognized | Create templates/ at project root |
Blank spec:inputs |
JSON schema validation error | Use spec: {} if no inputs needed |
Missing --- separator |
YAML parsing error | Add --- between spec and jobs |
| Wrong input reference syntax | Variable not interpolated | Use $[[ inputs.name ]] not ${inputs.name} |
| No .gitlab-ci.yml testing | Component breaks without detection | Add test jobs that use the component |
| No .gitlab-ci.yml release job | Manual publishing required | Add automated release on version tags |
| Hardcoded domains | Component not portable | Use $CI_SERVER_FQDN and variables |
| Missing required inputs | Pipeline error for users | Either add default or document as required |
Create directory structure
mkdir -p my-component/templates
touch my-component/README.md
touch my-component/LICENSE.md
touch my-component/.gitlab-ci.yml
Create component template
templates/my-component.ymlspec:inputs with validation--- separator$[[ inputs.field ]] syntaxDocument in README
$CI_SERVER_FQDNConfigure testing
.gitlab-ci.ymlConfigure publishing
Verify checklist
For complete details, see:
