GitLab Skill

Overview

This skill provides comprehensive GitLab expertise across three critical domains: CI/CD pipeline configuration and optimization, GitLab Flavored Markdown (GLFM) documentation creation, and local pipeline testing with gitlab-ci-local. Use this skill when working on GitLab projects to create professional documentation, build efficient pipelines, or validate CI/CD changes locally.

Core Capabilities

1. GitLab CI/CD Pipeline Configuration

Configure and optimize GitLab CI/CD pipelines for efficient software delivery.

When to use:

• Creating or modifying .gitlab-ci.yml files
• Optimizing pipeline performance and build times
• Implementing caching strategies and artifact management
• Configuring conditional job execution
• Managing secrets and environment variables
• Setting up Docker-in-Docker workflows
• Troubleshooting failed pipeline jobs

Key practices:

• Start with clear pipeline architecture in YAML
• Use .gitlab-ci.yml include feature for modular configurations
• Optimize job dependencies to minimize unnecessary runs
• Leverage cache for dependencies to reduce build times
• Protect sensitive data with masked environment variables
• Implement comprehensive tests at each pipeline stage
• Monitor and adjust pipeline performance metrics continuously

Reference: See Pipeline Optimization Guide for detailed best practices and common patterns.

2. GitLab Flavored Markdown (GLFM) Documentation

Create clear, consistent, and GitLab-optimized documentation using GLFM syntax.

When to use:

• Writing README files for GitLab projects
• Creating Wiki pages with interactive elements
• Documenting APIs with proper syntax highlighting
• Building user guides with collapsible sections
• Adding process flow diagrams with Mermaid
• Creating changelogs with GitLab references

GLFM features:

• Alert blocks (note, tip, important, caution, warning)
• Collapsible sections with <details> tags
• Mermaid diagrams for visualizations
• Task lists with completion tracking
• GitLab references (#issue, !MR, @user)
• Table of contents generation
• Math expressions support
• Color chips for design documentation

CRITICAL syntax rules:

• Alert types MUST be lowercase: [!note], [!tip], [!important], [!caution], [!warning]
• Use <details><summary> on single line (not multi-line)
• No markdown syntax inside <summary> tags - use HTML equivalents
• Validate rendering with included validation script

Reference: See GLFM Syntax Reference for complete syntax guide and examples.

3. Local Pipeline Testing with gitlab-ci-local

Test GitLab CI/CD pipelines locally before pushing to GitLab, eliminating the need for commit-push-debug cycles.

When to use:

• Testing pipeline changes before pushing to GitLab
• Debugging failed pipeline jobs locally
• Validating release workflows without creating actual releases
• Testing specific jobs or stages in isolation
• Verifying conditional job execution logic
• Checking artifact generation and dependencies

Setup workflow:

1. Install gitlab-ci-local: npm install -g gitlab-ci-local
2. Configure authentication tokens in $HOME/.gitlab-ci-local/variables.yml
3. Set project-specific variables in .gitlab-ci-local-variables.yml
4. Run jobs locally: gitlab-ci-local <job-name>

Common operations:

• List jobs: gitlab-ci-local --list
• Preview configuration: gitlab-ci-local --preview
• Run specific stage: gitlab-ci-local --stage test
• Run with dependencies: gitlab-ci-local --needs release
• Debug with timestamps: gitlab-ci-local --timestamps job-name

Reference: See GitLab CI Local Guide for complete setup instructions, troubleshooting, and examples.

Quality Checklist

Use this checklist to ensure comprehensive GitLab deliverables:

For CI/CD Pipelines:

• .gitlab-ci.yml syntax validated and follows best practices
• Jobs and stages named descriptively and organized logically
• Caching configured correctly to reduce redundant work
• Secrets properly masked and environment variables secure
• Conditional execution prevents unnecessary resource use
• Artifacts utilized appropriately and cleaned regularly
• Timeout limits defined for each job
• Pipeline tested locally with gitlab-ci-local
• Documentation includes pipeline overview and architecture

For GLFM Documentation:

• All alert blocks use lowercase syntax ([!note], [!tip], etc.)
• Collapsible sections use single-line <details><summary> format
• No markdown syntax in <summary> tags
• Mermaid diagrams used for process flows
• Table of contents added for long documents
• GitLab references used for issues/MRs/users
• Code blocks have language tags
• Heading hierarchy is consistent
• Rendered output validated with validation script

For Local Testing:

• gitlab-ci-local installed and configured
• Authentication tokens set in home directory configuration
• Project-specific variables defined in tracked file
• Jobs tested locally before pushing to GitLab
• Artifacts verified in .gitlab-ci-local/artifacts/
• Configuration validated with --preview command

Resources

This skill includes comprehensive reference materials and utilities:

scripts/

validate-glfm.py - Python script for validating GLFM rendering via GitLab's Markdown API.

Usage:

# Validate a markdown file
uv run --with requests ./scripts/validate-glfm.py --file README.md

# Validate inline markdown
uv run --with requests ./scripts/validate-glfm.py --markdown "> [!note]\n> Test alert"

# Save rendered HTML
uv run --with requests ./scripts/validate-glfm.py --file test.md --output rendered.html

Features:

• Automatic GITLAB_TOKEN loading from environment
• File or inline markdown input
• HTML output to stdout or file
• Verbose debugging mode
• Proper error handling and retry logic

references/

glfm-syntax.md - Complete GitLab Flavored Markdown syntax reference with examples, common mistakes, and best practices.

gitlab-ci-local-guide.md - Comprehensive guide for setting up and using gitlab-ci-local, including authentication configuration, troubleshooting, and real-world examples.

pipeline-optimization.md - Best practices for optimizing GitLab CI/CD pipeline performance, including caching strategies, job parallelization, and Docker optimization.

common-patterns.md - Collection of common GitLab CI/CD pipeline patterns and reusable configuration examples.

Working Process

When using this skill:

1. Identify the domain - Determine if the task involves CI/CD configuration, documentation, or local testing
2. Review relevant references - Load appropriate reference files for detailed guidance
3. Apply best practices - Follow quality checklists and established patterns
4. Validate output - Test pipelines locally or validate GLFM rendering
5. Document decisions - Include comments and documentation for future maintainability

Getting Started

For CI/CD Pipeline Work:

1. Review Pipeline Optimization Guide
2. Check Common Patterns for reusable configurations
3. Test changes locally with gitlab-ci-local before pushing

For Documentation Work:

1. Review GLFM Syntax Reference
2. Use validation script to verify rendering
3. Follow quality checklist for GLFM compliance

For Local Testing Setup:

1. Follow GitLab CI Local Guide setup instructions
2. Configure authentication tokens in home directory
3. Test pipeline execution locally before committing