GitLab CI/CD Pipeline Generator

Overview

Generate production-ready GitLab CI/CD pipeline configurations following current best practices, security standards, and naming conventions. All generated resources are automatically validated using the devops-skills:gitlab-ci-validator skill to ensure syntax correctness and compliance with best practices.

Trigger Phrases

Use this skill when the user asks for GitLab CI/CD generation requests such as:

• "Create a .gitlab-ci.yml for..."

• "Build a GitLab pipeline for Node/Python/Java..."

• "Add Docker build and deploy jobs in GitLab CI"

• "Set up GitLab parent-child or multi-project pipelines"

• "Include SAST/dependency scanning templates in GitLab CI"

Execution Model

Follow this deterministic flow in order:

• Classify request complexity (targeted , lightweight , or full ).

• Load only the required reference tier for that complexity.

• Output the matching response profile for the selected mode.

• For complete pipeline generation, start from the closest template and customize.

• Validate complete pipelines with strict Critical/High gates.

• Present output with validation status and template/version notes.

If tooling is unavailable, use the documented fallback branch and report it explicitly.

Mode Routing (Quick Decision)

Request shape Mode Required references Output profile

Simple single-file pipeline with common jobs/stages and low risk Lightweight Tier 1 (+ Tier 2 only if needed) Lightweight confirmation + compact final sections

Multi-environment deploy, advanced rules , includes/templates, security/compliance-sensitive workflow, or unclear/risky requirement Full Tier 1 + Tier 2 (Tier 3 only if needed) Full confirmation + full final sections

Review/Q&A/snippet/focused fix (not full file generation) Targeted Only directly relevant files Concise targeted response (no full boilerplate)

When uncertain on a complete-generation request, route to Full mode.

MANDATORY PRE-GENERATION STEPS

CRITICAL: Before generating any complete GitLab CI/CD pipeline, complete these steps.

Step 1: Classify Complexity (REQUIRED)

Mode Use When Minimum Confirmation

Targeted Review/Q&A/snippet/focused fix where full pipeline generation is not requested Concise targeted response

Lightweight Simple single-file pipeline, common stages/jobs, no advanced GitLab features, no sensitive deploy/security customization Lightweight confirmation

Full Multi-environment deploys, includes/templates, advanced rules logic, security scanning customization, compliance-sensitive workflows, or any unclear/risky request Full confirmation

When uncertain on a complete-generation request, default to Full mode.

Step 2: Load References by Tier (REQUIRED)

Use an open/read action to load references based on the selected mode.

Targeted mode (review/Q&A/snippet/focused fix):

• Load only directly relevant references/templates for the scoped request.

• Do not enforce Full-generation Tier 1/Tier 2 checklist items.

Tier 1 (Required for complete pipeline generation in Lightweight and Full modes):

• references/best-practices.md

• baseline security, performance, naming

• references/common-patterns.md

• starting pattern selection

• Matching template from assets/templates/ :

• Docker pipelines -> assets/templates/docker-build.yml

• Kubernetes deployments -> assets/templates/kubernetes-deploy.yml

• Multi-project pipelines -> assets/templates/multi-project.yml

• Basic pipelines -> assets/templates/basic-pipeline.yml

Tier 2 (Required for Full mode; optional for Lightweight mode):

• references/gitlab-ci-reference.md

• keyword/syntax edge cases

• references/security-guidelines.md

• security-sensitive controls

Tier 3 (Conditional external docs lookup):

• Use only when local references do not cover requested features or version-specific behavior.

• Follow the lookup flow in "Handling GitLab CI/CD Documentation Lookup."

If a required local reference or template is unavailable:

• Report the exact missing path.

• Continue with available references and mark assumptions explicitly.

• Do not claim production-ready confidence until missing critical inputs are resolved.

Step 3: Confirm Understanding (EXPLICIT OUTPUT REQUIRED)

Lightweight Confirmation Mode

Use for simple requests only.

Required format:

Reference Analysis Complete (Lightweight)

Pattern: [Pattern name] from common-patterns.md Template: [Template file] Key standards to enforce:

• [2-3 concrete standards]

Example:

Reference Analysis Complete (Lightweight)

Pattern: Basic Build-Test-Deploy from common-patterns.md Template: assets/templates/basic-pipeline.yml Key standards to enforce:

• Pin runtime image versions (no :latest)
• Add explicit job timeouts
• Use rules instead of deprecated only/except

Full Confirmation Mode

Use for complex or security-sensitive requests.

Required format:

Reference Analysis Complete (Full)

Pipeline Pattern Identified: [Pattern name] from common-patterns.md

• [Brief description of why this pattern fits]

Best Practices to Apply:

• [List 3-5 key best practices relevant to this pipeline]

Security Guidelines:

• [List security measures to implement]

Template Foundation: [Template file name]

• [What will be customized from this template]

Example:

Reference Analysis Complete (Full)

Pipeline Pattern Identified: Docker Build + Kubernetes Deployment from common-patterns.md

• User needs containerized deployment to K8s clusters with staging/production environments

Best Practices to Apply:

• Pin all Docker images to specific versions (not :latest)
• Use caching for pip dependencies
• Implement DAG optimization with needs keyword
• Set explicit timeout on all jobs (15-20 minutes)
• Use resource_group for deployment jobs

Security Guidelines:

• Use masked CI/CD variables for secrets (KUBE_CONTEXT, registry credentials)
• Include container scanning with Trivy
• Never expose secrets in logs

Template Foundation: assets/templates/docker-build.yml + assets/templates/kubernetes-deploy.yml

• Combine Docker build pattern with K8s kubectl deployment
• Add Python-specific test jobs

Skipping confirmation is not allowed for complete pipeline generation.

Core Capabilities

1. Generate Basic CI/CD Pipelines

Create complete, production-ready .gitlab-ci.yml files with proper structure, security best practices, and efficient CI/CD patterns.

When to use:

• User requests: "Create a GitLab pipeline for...", "Build a CI/CD pipeline...", "Generate GitLab CI config..."

• Scenarios: CI/CD pipelines, automated testing, build automation, deployment pipelines

Process:

• Understand the user's requirements (what needs to be automated)

• Identify stages, jobs, dependencies, and artifacts

• Use assets/templates/basic-pipeline.yml as structural foundation

• Reference references/best-practices.md for implementation patterns

• Reference references/common-patterns.md for standard pipeline patterns

• Generate the pipeline following these principles:

• Use semantic stage and job names

• Pin Docker images to specific versions (not :latest)

• Implement proper secrets management with masked variables

• Use caching for dependencies to improve performance

• Implement proper artifact handling with expiration

• Use needs keyword for DAG optimization when appropriate

• Add proper error handling with retry and allow_failure

• Use rules instead of deprecated only/except

• Set explicit timeout for all jobs (10-30 minutes typically)

• Add meaningful job descriptions in comments

• ALWAYS validate the generated pipeline using the devops-skills:gitlab-ci-validator skill

• If validation fails, fix the issues and re-validate

Example structure:

Basic CI/CD Pipeline

Builds, tests, and deploys the application

stages:

• build
• test
• deploy

Global variables

variables: NODE_VERSION: "20" DOCKER_DRIVER: overlay2

Default settings for all jobs

default: image: node:20-alpine timeout: 20 minutes # Default timeout for all jobs cache: key: ${CI_COMMIT_REF_SLUG} paths: - node_modules/ before_script: - echo "Starting job ${CI_JOB_NAME}" tags: - docker interruptible: true

Build stage - Compiles the application

build-application: stage: build timeout: 15 minutes script: - npm ci - npm run build artifacts: paths: - dist/ expire_in: 1 hour rules: - changes: - src/**/* - package*.json when: always - when: on_success

Test stage

test-unit: stage: test needs: [build-application] script: - npm run test:unit coverage: '/Coverage: \d+.\d+%/' artifacts: reports: junit: junit.xml coverage_report: coverage_format: cobertura path: coverage/cobertura-coverage.xml

test-lint: stage: test needs: [] # Can run immediately script: - npm run lint allow_failure: true

Deploy stage

deploy-staging: stage: deploy needs: [build-application, test-unit] script: - npm run deploy:staging environment: name: staging url: https://staging.example.com rules: - if: $CI_COMMIT_BRANCH == "develop" when: manual

deploy-production: stage: deploy needs: [build-application, test-unit] script: - npm run deploy:production environment: name: production url: https://example.com rules: - if: $CI_COMMIT_BRANCH == "main" when: manual resource_group: production

2. Generate Docker Build Pipelines

Create pipelines for building, testing, and pushing Docker images to container registries.

When to use:

• User requests: "Create a Docker build pipeline...", "Build and push Docker images..."

• Scenarios: Container builds, multi-stage Docker builds, registry pushes

Process:

• Understand the Docker build requirements (base images, registries, tags)

• Use assets/templates/docker-build.yml as foundation

• Implement Docker-in-Docker or Kaniko for builds

• Configure registry authentication

• Implement image tagging strategy

• Add security scanning if needed

• ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example:

stages:

• build
• scan
• push

variables: DOCKER_DRIVER: overlay2 IMAGE_NAME: $CI_REGISTRY_IMAGE IMAGE_TAG: $CI_COMMIT_SHORT_SHA

Build Docker image

docker-build: stage: build image: docker:24-dind timeout: 20 minutes services: - docker:24-dind before_script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY script: - docker build --cache-from $IMAGE_NAME:latest --tag $IMAGE_NAME:$IMAGE_TAG --tag $IMAGE_NAME:latest . - docker push $IMAGE_NAME:$IMAGE_TAG - docker push $IMAGE_NAME:latest rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH retry: max: 2 when: - runner_system_failure

Scan for vulnerabilities

container-scan: stage: scan image: aquasec/trivy:0.49.0 timeout: 15 minutes script: - trivy image --exit-code 0 --severity HIGH,CRITICAL $IMAGE_NAME:$IMAGE_TAG needs: [docker-build] allow_failure: true rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

3. Generate Kubernetes Deployment Pipelines

Create pipelines that deploy applications to Kubernetes clusters.

When to use:

• User requests: "Deploy to Kubernetes...", "Create K8s deployment pipeline..."

• Scenarios: Kubernetes deployments, Helm deployments, kubectl operations

Process:

• Identify the Kubernetes deployment method (kubectl, Helm, Kustomize)

• Use assets/templates/kubernetes-deploy.yml as foundation

• Configure cluster authentication (service accounts, kubeconfig)

• Implement proper environment management

• Add rollback capabilities

• ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example:

stages:

• build
• deploy

Kubernetes deployment job

deploy-k8s: stage: deploy image: bitnami/kubectl:1.29 timeout: 10 minutes before_script: - kubectl config use-context $KUBE_CONTEXT script: - kubectl set image deployment/myapp myapp=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA -n $KUBE_NAMESPACE - kubectl rollout status deployment/myapp -n $KUBE_NAMESPACE --timeout=5m environment: name: production url: https://example.com kubernetes: namespace: production rules: - if: $CI_COMMIT_BRANCH == "main" when: manual resource_group: k8s-production retry: max: 2 when: - runner_system_failure

4. Generate Multi-Project Pipelines

Create pipelines that trigger other projects or use parent-child pipeline patterns.

When to use:

• User requests: "Create multi-project pipeline...", "Trigger other pipelines..."

• Scenarios: Monorepos, microservices, orchestration pipelines

Process:

• Identify the pipeline orchestration needs

• Use assets/templates/multi-project.yml or parent-child templates

• Configure proper artifact passing

• Implement parallel execution where appropriate

• ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example (Parent-Child):

Parent pipeline

stages:

• trigger

generate-child-pipeline: stage: trigger script: - echo "Generating child pipeline config" - | cat > child-pipeline.yml <<EOF stages: - build

  child-job:
    stage: build
    script:
      - echo "Running child job"
  EOF

artifacts: paths: - child-pipeline.yml

trigger-child: stage: trigger trigger: include: - artifact: child-pipeline.yml job: generate-child-pipeline strategy: depend needs: [generate-child-pipeline]

5. Generate Template-Based Configurations

Create reusable templates using extends, YAML anchors, and includes.

When to use:

• User requests: "Create reusable templates...", "Build modular pipeline config..."

• Scenarios: Template libraries, DRY configurations, shared CI/CD logic

Process:

• Identify common patterns to extract

• Create hidden jobs (prefixed with .)

• Use extends keyword for inheritance

• Organize into separate files with include

• ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example:

Hidden template jobs (include timeout in templates)

.node-template: image: node:20-alpine timeout: 15 minutes # Default timeout for jobs using this template cache: key: ${CI_COMMIT_REF_SLUG} paths: - node_modules/ before_script: - npm ci interruptible: true

.deploy-template: timeout: 10 minutes # Deploy jobs should have explicit timeout before_script: - echo "Deploying to ${ENVIRONMENT}" after_script: - echo "Deployment complete" retry: max: 2 when: - runner_system_failure - stuck_or_timeout_failure interruptible: false # Deploys should not be interrupted

Actual jobs using templates

build: extends: .node-template stage: build script: - npm run build

deploy-staging: extends: .deploy-template stage: deploy variables: ENVIRONMENT: staging script: - ./deploy.sh staging resource_group: staging

6. Handling GitLab CI/CD Documentation Lookup

Use this flow only when local references do not cover requested features or version-sensitive behavior.

Detection:

• User mentions specific GitLab features (e.g., "Auto DevOps", "SAST", "dependency scanning")

• User requests integration with GitLab templates

• Pipeline requires specific GitLab runner features

Process:

Identify the feature:

• Extract the GitLab feature or template name

• Determine if version-specific information is needed

Check local references first (Tier 1/Tier 2):

• references/common-patterns.md

• references/gitlab-ci-reference.md

• references/security-guidelines.md

Use Context7 first when external lookup is needed:

• Resolve library: mcp__context7__resolve-library-id

• Query docs: mcp__context7__query-docs

• Prefer GitLab official/library docs over secondary sources

Fallback to web search when Context7 is unavailable or insufficient:

• Use web.search_query

• Query pattern: "GitLab CI/CD [feature] documentation"

• Prefer results from docs.gitlab.com

Open and extract from specific docs pages when needed:

• Use web.open for selected documentation pages

• Capture required syntax, variables, and version constraints

Analyze discovered documentation for:

• Current recommended approach

• Required variables and configuration

• Template include syntax

• Best practices and security recommendations

• Example usage

If network tools are unavailable (offline/constrained environment):

• Continue using local references only

• State that external version verification could not be performed

• Add a version-assumption note in the final output

Generate pipeline using discovered information:

• Use correct template include syntax

• Configure required variables

• Add security best practices

• Include comments about versions and choices

Example with GitLab templates:

Include GitLab's security templates (use Jobs/ prefix for current templates)

include:

• template: Jobs/SAST.gitlab-ci.yml
• template: Jobs/Dependency-Scanning.gitlab-ci.yml

Customize SAST behavior via global variables

Note: Set variables globally rather than overriding template jobs

to avoid validation issues with partial job definitions

variables: SAST_EXCLUDED_PATHS: "spec, test, tests, tmp, node_modules" DS_EXCLUDED_PATHS: "node_modules, vendor" SECURE_LOG_LEVEL: "info"

Important: When using include with GitLab templates, the included jobs are fully defined in the template. If you need to customize them, prefer setting variables globally rather than creating partial job overrides (which will fail local validation because the validator cannot resolve the included template). GitLab merges the configuration at runtime, but local validators only see your .gitlab-ci.yml file.

Validation Workflow

CRITICAL: Every generated GitLab CI/CD configuration MUST be validated before presenting to the user.

Validation Process

Primary validation path: after generating a complete pipeline, invoke the devops-skills:gitlab-ci-validator skill:

Skill: devops-skills:gitlab-ci-validator

Script fallback path (if validator skill cannot be invoked):

PIPELINE_FILE="<generated-output-path>"

• Set PIPELINE_FILE to the exact generated file path (for example, pipelines/review.yml or .gitlab-ci.yml ).

• Fail fast if that file does not exist: if [[ ! -f "$PIPELINE_FILE" ]]; then echo "ERROR: CI file not found: $PIPELINE_FILE" >&2 exit 1 fi

From repository root

bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh "$PIPELINE_FILE"

From skills/gitlab-ci-generator directory

bash ../gitlab-ci-validator/scripts/validate_gitlab_ci.sh "$PIPELINE_FILE"

• If the script is not executable: chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh

• Optional API lint fallback when GitLab project context is available: jq --null-input --arg yaml "$(<"$PIPELINE_FILE")" '.content=$yaml'
  | curl --header "Content-Type: application/json"
  --url "https://gitlab.com/api/v4/projects/:id/ci/lint?include_merged_yaml=true"
  --data @-

Manual fallback path (only if both primary and script paths are unavailable):

• Run manual checks for YAML validity, stage/job references, and obvious secret exposure.

• Mark output as Validation status: Manual fallback (not fully verified) .

• Do not claim production-ready status if Critical/High risk cannot be confidently ruled out.

The validator skill/script checks:

• Validate YAML syntax

• Check GitLab CI/CD schema compliance

• Verify job references and dependencies

• Check for best practices violations

• Perform security scanning

• Report any errors, warnings, or issues

Analyze validation results and take action based on severity:

Severity Action Required

CRITICAL MUST fix before presenting. Pipeline is broken or severely insecure.

HIGH MUST fix before presenting. Significant security or functionality issues.

MEDIUM SHOULD fix before presenting. Apply fixes or explain why not applicable.

LOW MAY fix or acknowledge. Inform user of recommendations.

SUGGESTIONS Review and apply if beneficial. No fix required.

Fix-and-Revalidate Loop (MANDATORY for Critical/High issues):

While validation has CRITICAL or HIGH issues:

1. Edit the generated file to fix the issue
2. Re-run validation
3. Repeat until no CRITICAL or HIGH issues remain

Before presenting to user, ensure:

• Zero CRITICAL issues

• Zero HIGH issues

• MEDIUM issues either fixed OR explained why they're acceptable

• LOW issues and suggestions acknowledged

When presenting the validated configuration:

• State validation status clearly

• State validation path used (skill, script fallback, or manual fallback)

• List any remaining MEDIUM/LOW issues with explanations

• Include template/version freshness notes

• Provide usage instructions

• Mention any trade-offs made

Critical/High gate is strict and never optional for production-ready claims.

Validation Pass Criteria

Pipeline is READY to present when:

• ✅ Validation path executed (validator skill or script fallback)

• ✅ Syntax validation: PASSED

• ✅ Security scan: No CRITICAL or HIGH issues

• ✅ Best practices: Reviewed (warnings acceptable with explanation)

Pipeline is NOT READY when:

• ❌ Any syntax errors exist

• ❌ Any CRITICAL security issues exist

• ❌ Any HIGH security issues exist

• ❌ Job references are broken

• ❌ Only manual fallback was used and Critical/High risks cannot be ruled out

When to Skip Validation

Only skip validation when:

• Generating partial code snippets (not complete files)

• Creating examples for documentation purposes

• User explicitly requests to skip validation

Handling MEDIUM Severity Issues (REQUIRED OUTPUT)

When the validator reports MEDIUM severity issues, you MUST either fix them OR explain why they're acceptable. This explanation is REQUIRED in your output.

Required format for MEDIUM issue handling:

Validation Issues Addressed

MEDIUM Severity Issues

Example MEDIUM issue explanations:

Validation Issues Addressed

MEDIUM Severity Issues

When to FIX vs ACCEPT:

Scenario Action

Production/high-security environment FIX the issue

Issue has simple fix with no downside FIX the issue

Fix adds significant complexity ACCEPT with explanation

Fix requires external changes (e.g., CI/CD variables) ACCEPT with explanation

Issue is false positive for this context ACCEPT with explanation

Reviewing Suggestions (REQUIRED OUTPUT)

When the validator provides suggestions, you MUST briefly acknowledge them and explain whether they should be applied.

Required format:

Validator Suggestions Review

Example suggestions review:

Validator Suggestions Review

Template and Version Notes (REQUIRED OUTPUT)

After validation results, include a concise freshness note for templates and documentation assumptions.

Required format:

Template and Version Notes

• Template base: [assets/templates/<file>.yml]
• Template customization scope: [what changed from template]
• Version/doc basis: [Context7, docs.gitlab.com, or local references only]
• Freshness note: [exact date checked, or "external lookup unavailable"]
• Version-sensitive assumptions: [if any]

Example:

Template and Version Notes

• Template base: assets/templates/docker-build.yml
• Template customization scope: Added unit-test stage and environment-specific deploy rules
• Version/doc basis: docs.gitlab.com include-template docs + local references
• Freshness note: Verified template syntax on 2026-02-28
• Version-sensitive assumptions: Uses Jobs/SAST.gitlab-ci.yml template path

Usage Instructions Template (REQUIRED OUTPUT)

After presenting the validated pipeline, you MUST provide usage instructions. This is NOT optional.

Required format:

Usage Instructions

Required CI/CD Variables

Configure these variables in Settings → CI/CD → Variables:

Setup Steps

1. [First setup step]
2. [Second setup step] ...

Pipeline Behavior

• On push to develop: [What happens]
• On push to main: [What happens]
• On tag vX.Y.Z: [What happens]

Customization

[Any customization notes]

Example usage instructions:

Usage Instructions

Required CI/CD Variables

Configure these variables in Settings → CI/CD → Variables:

Note: CI_REGISTRY_USER, CI_REGISTRY_PASSWORD, and CI_REGISTRY are automatically provided by GitLab.

Kubernetes Integration Setup

1. Enable Kubernetes integration in Settings → Infrastructure → Kubernetes clusters
2. Add your cluster using the agent-based or certificate-based method
3. Create namespaces for staging and production if they don't exist:

   kubectl create namespace staging
   kubectl create namespace production
   
   

• Ensure deployment exists in the target namespaces before running the pipeline

Pipeline Behavior

• On push to develop : Runs tests → builds Docker image → deploys to staging automatically

• On push to main : Runs tests → builds Docker image → manual deployment to production

• On tag vX.Y.Z : Runs tests → builds Docker image → manual deployment to production

Customization

• Update APP_NAME variable to match your Kubernetes deployment name

• Modify environment URLs in deploy-staging and deploy-production jobs

• Add Helm deployment by uncommenting the Helm jobs in the template

Best Practices to Enforce

Reference references/best-practices.md for comprehensive guidelines. Key principles:

Mandatory Standards

1. Security First:

   • Pin Docker images to specific versions (not :latest)
   • Use masked variables for secrets ($CI_REGISTRY_PASSWORD should be masked)
   • Never expose secrets in logs
   • Validate inputs and sanitize variables
   • Use protected variables for sensitive environments

2. Performance:

   • Implement caching for dependencies (ALWAYS for npm, pip, maven, etc.)
   • Use needs keyword for DAG optimization (ALWAYS when jobs have dependencies)
   • Set artifact expiration to avoid storage bloat (ALWAYS set expire_in)
   • Use parallel execution when applicable (only if test framework supports sharding)
   • Minimize unnecessary artifact passing (use artifacts: false in needs when not needed)

3. Reliability:

   • Set explicit timeout for ALL jobs (prevents hanging jobs, typically 10-30 minutes)
     • Even when using default or extends for timeout inheritance, add explicit timeout to each job
     • This improves readability and avoids validator warnings about missing timeout
     • Example: A job using .deploy-template should still have timeout: 15 minutes explicitly set
   • Add retry logic for flaky operations (network calls, external API interactions)
   • Use allow_failure appropriately for non-critical jobs (linting, optional scans)
   • Use resource_group for deployment jobs (prevents concurrent deployments)
   • Add interruptible: true for test jobs (allows cancellation when new commits push)

4. Naming:

   • Job names: Descriptive, kebab-case (e.g., "build-application", "test-unit")
   • Stage names: Short, clear (e.g., "build", "test", "deploy")
   • Variable names: UPPER_SNAKE_CASE for environment variables
   • Environment names: lowercase (e.g., "production", "staging")

5. Configuration Organization:

   • Use extends for reusable configuration (PREFERRED over YAML anchors for GitLab CI)
   • Use include for modular pipeline files (organize large pipelines into multiple files)
   • Use rules instead of deprecated only/except (ALWAYS)
   • Define default settings for common configurations (image, timeout, cache, tags)
   • Use YAML anchors only when necessary for complex repeated structures within a single file
     • Note: extends is preferred because it provides better visualization in GitLab UI

6. Error Handling:

   • Set appropriate timeout values (ALWAYS - prevents hanging jobs)
   • Configure retry behavior for flaky operations (network calls, external APIs)
   • Use allow_failure: true for non-blocking jobs (linting, optional scans)
   • Add cleanup steps with after_script when needed (e.g., stopping test containers, cleanup)
   • Implement notification mechanisms when required (e.g., Slack integration for deployment failures)

Resources

References (Tiered Loading)

• references/best-practices.md (Tier 1: required for all) - Comprehensive GitLab CI/CD best practices

  • Security patterns, performance optimization
  • Pipeline design, configuration organization
  • Common patterns and anti-patterns
  • Use this: When implementing any GitLab CI/CD resource

• references/common-patterns.md (Tier 1: required for all) - Frequently used pipeline patterns

  • Basic CI pipeline patterns
  • Docker build and push patterns
  • Deployment patterns (K8s, cloud platforms)
  • Multi-project and parent-child patterns
  • Use this: When selecting which pattern to use

• references/gitlab-ci-reference.md (Tier 2: required for Full mode) - GitLab CI/CD YAML syntax reference

  • Complete keyword reference
  • Job configuration options
  • Rules and conditional execution
  • Variables and environments
  • Use this: For syntax and keyword details

• references/security-guidelines.md (Tier 2: required for Full mode) - Security best practices

  • Secrets management
  • Image security
  • Script security
  • Artifact security
  • Use this: For security-sensitive configurations

Assets (Templates to Customize)

• assets/templates/basic-pipeline.yml - Complete basic pipeline template
• assets/templates/docker-build.yml - Docker build pipeline template
• assets/templates/kubernetes-deploy.yml - Kubernetes deployment template
• assets/templates/multi-project.yml - Multi-project orchestration template

How to use templates:

1. Copy the relevant template structure
2. Replace all [PLACEHOLDERS] with actual values
3. Customize logic based on user requirements
4. Remove unnecessary sections
5. Validate the result

Typical Workflow Example

User request: "Create a CI/CD pipeline for a Node.js app with testing and Docker deployment"

Process:

1. ✅ Understand requirements:

   • Node.js application
   • Run tests (unit, lint)
   • Build Docker image
   • Deploy to container registry
   • Trigger on push and merge requests

2. ✅ Reference resources:

   • Check references/best-practices.md for pipeline structure
   • Check references/common-patterns.md for Node.js + Docker pattern
   • Use assets/templates/docker-build.yml as base

3. ✅ Generate pipeline:

   • Define stages (build, test, dockerize, deploy)
   • Create build job with caching
   • Create test jobs (unit, lint) with needs optimization
   • Create Docker build job
   • Add proper artifact management
   • Pin Docker images to versions
   • Include proper secrets handling

4. ✅ Validate:

   • Invoke devops-skills:gitlab-ci-validator skill
   • Fix any reported issues
   • Re-validate if needed

5. ✅ Present to user:

   • Show validated pipeline
   • Explain key sections
   • Provide usage instructions
   • Mention successful validation

Common Pipeline Patterns

Basic Three-Stage Pipeline

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script: make build

test-job:
  stage: test
  script: make test

deploy-job:
  stage: deploy
  script: make deploy
  when: manual

DAG Pipeline with Needs

stages:
  - build
  - test
  - deploy

build-frontend:
  stage: build
  script: npm run build:frontend

build-backend:
  stage: build
  script: npm run build:backend

test-frontend:
  stage: test
  needs: [build-frontend]
  script: npm test:frontend

test-backend:
  stage: test
  needs: [build-backend]
  script: npm test:backend

deploy:
  stage: deploy
  needs: [test-frontend, test-backend]
  script: make deploy

Conditional Execution with Rules

deploy-staging:
  script: deploy staging
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
      when: always
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

deploy-production:
  script: deploy production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - when: never

Matrix Parallel Jobs

test:
  parallel:
    matrix:
      - NODE_VERSION: ['18', '20', '22']
        OS: ['ubuntu', 'alpine']
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm test

Error Messages and Troubleshooting

If devops-skills:gitlab-ci-validator reports errors:

- Syntax errors: Fix YAML formatting, indentation, or structure

- Job reference errors: Ensure referenced jobs exist in needs/dependencies

- Stage errors: Verify all job stages are defined in stages list

- Rule errors: Check rules syntax and variable references

- Security warnings: Address hardcoded secrets and image pinning

If GitLab documentation is not found:

- Try Context7 first: mcp__context7__resolve-library-id
 -> mcp__context7__query-docs

- If needed, run web.search_query
 scoped to docs.gitlab.com

- Open specific pages with web.open
 and extract only required syntax/variables

- If offline, continue with local references and add version-assumption notes

PRE-DELIVERY CHECKLIST

MANDATORY: Before presenting ANY generated pipeline to the user, verify ALL items:

Mode and References

-  Complexity mode selected (Targeted
, Lightweight
, or Full
)

-  For Targeted mode: only directly relevant files/references loaded

-  For Lightweight/Full modes: read references/best-practices.md
 before generating

-  For Lightweight/Full modes: read references/common-patterns.md
 before generating

-  For Lightweight/Full modes: read appropriate template from assets/templates/
 for the pipeline type

-  For Full mode: read references/gitlab-ci-reference.md

-  For Full mode: read references/security-guidelines.md

-  Output explicit confirmation statement for Lightweight/Full modes

Generation Standards Applied

-  All Docker images pinned to specific versions (no :latest
)

-  All jobs have explicit timeout
 (10-30 minutes typically)

-  default
 block includes timeout
 if defined

-  Hidden templates (.template-name
) include timeout

-  Caching configured for dependency installation

-  needs
 keyword used for DAG optimization where appropriate

-  rules
 used (not deprecated only
/except
)

-  resource_group
 configured for deployment jobs

-  Artifacts have expire_in
 set

-  Secrets use masked CI/CD variables (not hardcoded)

Validation Completed

-  Validation executed via devops-skills:gitlab-ci-validator
 or script fallback

-  Zero CRITICAL issues

-  Zero HIGH issues

-  MEDIUM issues addressed (fixed OR explained in output using required format)

-  LOW issues acknowledged (listed in output)

-  Suggestions reviewed (using required format)

-  Re-validated after any fixes

-  If only manual fallback was available: output marked as not fully verified

Presentation Ready

-  Validation status stated clearly

-  Validation path stated clearly (skill, script fallback, or manual fallback)

-  MEDIUM/LOW issues explained (with table format)

-  Suggestions review provided (with table format)

-  Template and version notes provided (with required format)

-  Usage instructions provided (with required sections)

-  Key sections explained

If any checkbox is unchecked, DO NOT present the pipeline. Complete the missing steps first.

Required Output Sections

Use the smallest valid output profile for the selected mode.

Full mode (complete/complex pipeline):

- Reference Analysis Complete (from Step 3)

- Generated Pipeline (the .gitlab-ci.yml
 content)

- Validation Results Summary (pass/fail status)

- Validation Issues Addressed (MEDIUM issues table)

- Validator Suggestions Review (suggestions table)

- Template and Version Notes (template base + freshness/version assumptions)

- Usage Instructions (variables, setup, behavior)

Lightweight mode (complete/simple pipeline):

- Reference Analysis Complete (Lightweight)

- Generated Pipeline

- Validation Results Summary

- Template and Version Notes

- Usage Instructions

- Add Validation Issues Addressed only when MEDIUM issues exist.

- Add Validator Suggestions Review only when suggestions are present.

Targeted mode (review/Q&A/snippet/focused fix):

- Provide only the directly requested artifact/answer and a concise rationale.

- Include validation/fallback disclosure if validation was not run.

- Do not force full pipeline-generation sections.

Done Criteria

This skill execution is done when:

- Simple requests use Lightweight mode without unnecessary Tier 2 loading.

- Complex requests use Full mode with Tier 2 references and complete confirmation.

- Validation enforces strict Critical/High gates before production-ready claims.

- Output includes template/version freshness notes plus usage instructions.

- Any fallback path is explicit and does not hide verification gaps.

Summary

Always follow this sequence when generating GitLab CI/CD pipelines:

- Classify Complexity - choose Targeted
, Lightweight
, or Full
 mode.

- Load References - use tiered loading:

- For Targeted
 mode, load only directly relevant files.

- For Lightweight/Full
 modes, load:

- references/best-practices.md

- references/common-patterns.md

- Plus the appropriate template from assets/templates/

- For Full
 mode, also load:

- references/gitlab-ci-reference.md

- references/security-guidelines.md

- Confirm - Output targeted response or Lightweight/Full reference analysis as required by mode.

- Generate - Use templates and follow standards (security, caching, naming, explicit timeout on ALL jobs).

- Lookup Docs When Needed - Context7 first, then web.search_query
/web.open
, with offline fallback notes when constrained.

- Validate - Use devops-skills:gitlab-ci-validator
, script fallback if needed.

- Fix - Resolve all Critical/High issues, address Medium issues.

- Verify Checklist - Confirm all pre-delivery checklist items.

- Present - Deliver output with validation summary, template/version notes, and usage instructions.

Generate GitLab CI/CD pipelines that are:

- ✅ Secure with pinned images and proper secrets handling

- ✅ Following current best practices and conventions

- ✅ Using proper configuration organization (extends, includes)

- ✅ Optimized for performance (caching, needs, DAG)

- ✅ Properly documented with usage instructions

- ✅ Validated with zero Critical/High issues

- ✅ Production-ready and maintainable