GitLab CI Generator

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:

1. Classify request complexity (targeted, lightweight, or full).
2. Load only the required reference tier for that complexity.
3. Output the matching response profile for the selected mode.
4. For complete pipeline generation, start from the closest template and customize.
5. Validate complete pipelines with strict Critical/High gates.
6. 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)

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)

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):

1. references/best-practices.md - baseline security, performance, naming
2. references/common-patterns.md - starting pattern selection
3. 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):

1. references/gitlab-ci-reference.md - keyword/syntax edge cases
2. 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:

1. Understand the user's requirements (what needs to be automated)
2. Identify stages, jobs, dependencies, and artifacts
3. Use assets/templates/basic-pipeline.yml as structural foundation
4. Reference references/best-practices.md for implementation patterns
5. Reference references/common-patterns.md for standard pipeline patterns
6. 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
7. ALWAYS validate the generated pipeline using the devops-skills:gitlab-ci-validator skill
8. 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:

1. Understand the Docker build requirements (base images, registries, tags)
2. Use assets/templates/docker-build.yml as foundation
3. Implement Docker-in-Docker or Kaniko for builds
4. Configure registry authentication
5. Implement image tagging strategy
6. Add security scanning if needed
7. 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:

1. Identify the Kubernetes deployment method (kubectl, Helm, Kustomize)
2. Use assets/templates/kubernetes-deploy.yml as foundation
3. Configure cluster authentication (service accounts, kubeconfig)
4. Implement proper environment management
5. Add rollback capabilities
6. 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:

1. Identify the pipeline orchestration needs
2. Use assets/templates/multi-project.yml or parent-child templates
3. Configure proper artifact passing
4. Implement parallel execution where appropriate
5. 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:

1. Identify common patterns to extract
2. Create hidden jobs (prefixed with .)
3. Use extends keyword for inheritance
4. Organize into separate files with include
5. 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:

1. Identify the feature:

   • Extract the GitLab feature or template name
   • Determine if version-specific information is needed

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

   • references/common-patterns.md
   • references/gitlab-ci-reference.md
   • references/security-guidelines.md

3. 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

4. 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

5. Open and extract from specific docs pages when needed:

   • Use web.open for selected documentation pages
   • Capture required syntax, variables, and version constraints

6. Analyze discovered documentation for:

   • Current recommended approach
   • Required variables and configuration
   • Template include syntax
   • Best practices and security recommendations
   • Example usage

7. 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

8. 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

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

   Skill: devops-skills:gitlab-ci-validator

2. 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 @-

3. 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.

4. 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

5. 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.

6. 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

7. 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

8. 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.