building-gitlab-ci-components — Claude Code skill
building-gitlab-ci-components — a guided workflow for reusable GitLab CI/CD components, covering project structure, inputs, tests, and catalog release setup.
Unlicense 1 installs ★ 5 updated 2026-01-27
npx skills add nagyv/claude-commands --skill building-gitlab-ci-components -a claude-codeWhat building-gitlab-ci-components does
This skill walks through building reusable GitLab CI/CD components with GitLab’s expected project layout. It covers the templates/ directory, required README.md, LICENSE.md, and .gitlab-ci.yml files, plus the test and release jobs needed for a component project. Use it for a new component, for packaging an existing pipeline template, or for preparing a project for the CI/CD Catalog.
The guide explains spec:inputs, input types and validation, $[[ inputs.field-name ]] references, and the --- separator between the specification and job definitions. It also recommends $CI_SERVER_FQDN and $CI_API_V4_URL instead of fixed domains or API addresses. If the separator is missing, the template structure is invalid.
What it helps with
- create a reusable GitLab CI component layout
- define typed inputs with
spec:inputs - test component behavior through a pipeline job
- publish catalog releases from semantic version tags
- write README usage and input tables
Example prompts for the agent
- Create a reusable GitLab CI component for building a Docker image and check its required project files.
- Review
spec:inputs,$[[ inputs.field-name ]]references, and the---separator in this component. - Set up
.gitlab-ci.ymlwith a component test job and a tag-based release job.
How to install building-gitlab-ci-components
1Skills CLI (Vercel)
npx skills add nagyv/claude-commands --skill building-gitlab-ci-components -a claude-code2Manually: put the files in place
~/.claude/skills/building-gitlab-ci-components/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/building-gitlab-ci-components/
1Skills CLI (Vercel)
npx skills add nagyv/claude-commands --skill building-gitlab-ci-components -a codex2Manually: put the files in place
.agents/skills/building-gitlab-ci-components/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nagyv/claude-commands --skill building-gitlab-ci-components -a cursor2Manually: put the files in place
.cursor/skills/building-gitlab-ci-components/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nagyv/claude-commands skills/building-gitlab-ci-components2Manually: put the files in place
.github/skills/building-gitlab-ci-components/SKILL.md1Skills CLI (Vercel)
npx skills add nagyv/claude-commands --skill building-gitlab-ci-components -a gemini-cli2Platform CLI
gemini skills install https://github.com/nagyv/claude-commands --path skills/building-gitlab-ci-componentsManually: put the files in place
.devin/skills/building-gitlab-ci-components/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nagyv/claude-commands --skill building-gitlab-ci-components -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about building-gitlab-ci-components
How do I install building-gitlab-ci-components in Claude Code?
Run npx skills add nagyv/claude-commands --skill building-gitlab-ci-components -a claude-code, then check ~/.claude/skills/building-gitlab-ci-components/SKILL.md.
What does building-gitlab-ci-components do?
It guides the creation of reusable GitLab CI/CD components, including their file layout, inputs, behavior tests, and CI/CD Catalog release configuration.
Which files does a component project need?
The project needs README.md, LICENSE.md, and .gitlab-ci.yml. Component definitions go under templates/ as .yml files or directories containing template.yml.
Source text
SKILL.md · Unlicense
---
name: building-gitlab-ci-components
description: 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 avoid missing required files, directory structure, input specifications, or testing/publishing configuration
---
# Building GitLab CI Components
## Overview
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.
## When to Use
Use this skill when:
- Creating a new reusable CI/CD component
- Packaging existing pipeline configuration for sharing
- Publishing components to the GitLab CI/CD Catalog
- Setting up a component project structure
## Critical Requirements Checklist
These are commonly missed - verify each one:
- [ ] **Directory structure**: `templates/` directory with components as `.yml` files or subdirectories with `template.yml`
- [ ] **Required files**: README.md, LICENSE.md, .gitlab-ci.yml present
- [ ] **Testing configuration**: .gitlab-ci.yml includes jobs to test component behavior
- [ ] **Publishing configuration**: .gitlab-ci.yml includes release job for catalog publishing
- [ ] **Input specification**: `spec:inputs` syntax correct with proper types and validation
- [ ] **Input usage**: Inputs referenced as `$[[ inputs.field-name ]]` in template
- [ ] **YAML separator**: `---` separator present between spec and job definitions
- [ ] **No hardcoded values**: Use `$CI_SERVER_FQDN` and inputs instead of hardcoded domains/values
## Directory Structure
### Single Component Project
```
my-component/
├── templates/
│ └── my-component.yml # Component definition
├── README.md # Documentation with usage examples
├── LICENSE.md # Required license file
└── .gitlab-ci.yml # Testing and publishing
```
### Multi-Component Project
```
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:**
- Maximum 100 components per project (GitLab 18.5+)
- Earlier versions: 30 components maximum
## Component Template Structure
### Basic Template with Inputs
```yaml
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 inputs
- Inputs without `default` are required
### Input Specification
**Input attributes:**
- `type`: Data type (string, number, boolean, array)
- `default`: Default value (makes input optional)
- `description`: Documents the input purpose
**Validation options:**
- `type`: Enforces data type
- `regex`: Pattern validation (e.g., `^v\d+\.\d+(\.\d+)?$`)
- `options`: Restricts to allowed values (e.g., `['dev', 'staging', 'prod']`)
**Empty spec handling:**
```yaml
# If no inputs needed, use empty spec (not blank)
spec: {}
---
```
**Complete input specification reference:** https://docs.gitlab.com/ci/inputs/
## .gitlab-ci.yml for Testing
```yaml
# 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
```
## .gitlab-ci.yml for Publishing
```yaml
# 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:**
- Use semantic versioning: `1.0.0`, `2.3.4`, etc.
- Tag precedence: commit SHA > tag > branch
- Partial versions supported: `1.2` matches latest `1.2.*`
- Use `~latest` for absolute latest version (not recommended for production)
## README.md Requirements
```markdown
# 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/[email protected]
inputs:
image_name: myapp
image_tag: v1.2.3
\`\`\`
## Contributing
Guidelines for contributing to this component.
```
**Required sections:**
- Component summary and capabilities
- Input documentation (use table format)
- Usage examples with `$CI_SERVER_FQDN` (never hardcode domain)
- For multi-component projects: table of contents and sections per component
## Best Practices
### Avoid Hardcoding
```yaml
# ❌ 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 references
- Inputs for user-configurable values
**All predefined variables:** https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
### Avoid Global Keywords
```yaml
# ❌ 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.
## Component Usage Format
```yaml
include:
- component: <FQDN>/<project-path>/<component-name>@<version>
inputs:
field: value
```
**Example:**
```yaml
include:
- component: $CI_SERVER_FQDN/my-org/security/[email protected]
inputs:
stage: security-scan
fail_on_detection: true
```
## Common Mistakes
| 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 |
## Quick Start Workflow
1. **Create directory structure**
```bash
mkdir -p my-component/templates
touch my-component/README.md
touch my-component/LICENSE.md
touch my-component/.gitlab-ci.yml
```
2. **Create component template**
- Create `templates/my-component.yml`
- Add `spec:inputs` with validation
- Add `---` separator
- Define jobs using `$[[ inputs.field ]]` syntax
3. **Document in README**
- Usage examples with `$CI_SERVER_FQDN`
- Input table with types and descriptions
- Contribution guidelines
4. **Configure testing**
- Add test job to `.gitlab-ci.yml`
- Test component with various input combinations
5. **Configure publishing**
- Add release job triggered by semantic version tags
- Test with a pre-release tag first
6. **Verify checklist**
- Run through Critical Requirements Checklist above
- Ensure no hardcoded values
- Confirm all inputs documented
## Reference Documentation
For complete details, see:
- [GitLab CI Components Documentation](https://docs.gitlab.com/ci/components/)
- [Input Specification Reference](https://docs.gitlab.com/ci/inputs/)
- [Predefined Variables Reference](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
- [CI/CD Catalog](https://docs.gitlab.com/ci/components/catalog.html)
© nagyv · Unlicense · nagyv/claude-commands