pantheon-org/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 validated using the devops-skills:gitlab-ci-validator skill before delivery.

---

MANDATORY PRE-GENERATION STEPS

CRITICAL: Before generating ANY pipeline, complete these steps in order:

Step 1: Load Reference Files (ALL REQUIRED)

Use the Read tool to load all four reference files plus the relevant template:

1. references/best-practices.md       — Security, performance, and naming patterns
2. references/common-patterns.md      — Standard pipeline patterns as foundation
3. references/gitlab-ci-reference.md  — Syntax reference and keyword details
4. references/security-guidelines.md  — Security-sensitive configurations

Template selection:

• 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

Step 2: Output Confirmation Before Generating

After reading references, output this confirmation before proceeding:

## Reference Analysis Complete

**Pipeline Pattern Identified:** [Pattern name] from common-patterns.md
- [Why this pattern fits]

**Best Practices to Apply:**
- [3–5 key best practices relevant to this pipeline]

**Security Guidelines:**
- [Security measures to implement]

**Template Foundation:** [Template file name]
- [What will be customized]

---

Core Capabilities

1. Basic CI/CD Pipelines

Generate complete .gitlab-ci.yml files with proper structure, security best practices, and efficient CI/CD patterns. Use assets/templates/basic-pipeline.yml as structural foundation, referencing references/best-practices.md and references/common-patterns.md.

Apply these principles:

• Semantic stage and job names (kebab-case)
• Pin Docker images to specific versions (never :latest)
• Masked variables for secrets; never hardcode credentials
• Caching for dependencies (npm, pip, maven, etc.)
• Artifact expiration (expire_in always set)
• needs keyword for DAG optimization
• rules instead of deprecated only/except
• Explicit timeout on ALL jobs (10–30 minutes typically)
• retry for flaky operations (network, external APIs)
• resource_group for deployment jobs

Validate per the Validation Workflow section.

Minimal example:

stages: [build, test, deploy]

variables:
  NODE_VERSION: "20"

default:
  image: node:20-alpine
  timeout: 20 minutes
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths: [node_modules/]
  interruptible: true

build-application:
  stage: build
  timeout: 15 minutes
  script: [npm ci, npm run build]
  artifacts:
    paths: [dist/]
    expire_in: 1 hour

test-unit:
  stage: test
  needs: [build-application]
  script: [npm run test:unit]
  artifacts:
    reports:
      junit: junit.xml

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
  timeout: 15 minutes

2. Docker Build Pipelines

Create pipelines for building, scanning, and pushing Docker images to container registries. Use assets/templates/docker-build.yml as foundation with Docker-in-Docker or Kaniko, registry authentication via predefined variables, image tagging strategy ($CI_COMMIT_SHORT_SHA), and container security scanning (Trivy or GitLab template). Validate per the Validation Workflow section.

Minimal example:

variables:
  IMAGE_NAME: $CI_REGISTRY_IMAGE
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

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 .
    - docker push $IMAGE_NAME:$IMAGE_TAG
  retry:
    max: 2
    when: [runner_system_failure]

3. Kubernetes Deployment Pipelines

Create pipelines deploying to Kubernetes clusters via kubectl, Helm, or Kustomize. Use assets/templates/kubernetes-deploy.yml as foundation with cluster authentication via $KUBE_CONTEXT, environment management, and rollback capabilities. Validate per the Validation Workflow section.

Minimal example:

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
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  resource_group: k8s-production

4. Multi-Project Pipelines

Create pipelines that trigger other projects or use parent-child patterns for monorepos and microservices. Use assets/templates/multi-project.yml or parent-child templates with artifact passing between pipelines and parallel execution where appropriate. Validate per the Validation Workflow section.

5. Reusable Template Configurations

Create modular, DRY configurations using extends, YAML anchors, and include. Extract common patterns into hidden jobs (.template-name), use extends for inheritance (preferred over YAML anchors), organize into separate files with include, and include explicit timeout in all templates. Validate per the Validation Workflow section.

Minimal example:

.node-template:
  image: node:20-alpine
  timeout: 15 minutes
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths: [node_modules/]
  before_script: [npm ci]
  interruptible: true

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

6. GitLab Feature Documentation Lookup

When the user requests specific GitLab features (Auto DevOps, SAST, dependency scanning, etc.):

1. Search for current docs: "GitLab CI/CD [feature] documentation 2025"
2. If Context7 MCP is available: use mcp__context7__resolve-library-id then mcp__context7__get-library-docs
3. If specific pages needed: use WebFetch on docs.gitlab.com
4. Generate pipeline using discovered syntax, required variables, and template include paths

When using GitLab include templates:

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

variables:
  SAST_EXCLUDED_PATHS: "spec, test, tests, tmp"

Note: Customize included template jobs via global variables rather than partial job overrides. GitLab merges at runtime, but local validators only see your file—partial overrides will fail validation.

---

Validation Workflow

Every complete pipeline MUST be validated before presenting to the user.

Process

1. After generating, invoke devops-skills:gitlab-ci-validator
2. Act on results by severity (CRITICAL/HIGH: must fix; MEDIUM: fix or explain; LOW: acknowledge; SUGGESTIONS: review and apply if beneficial)
3. Fix CRITICAL/HIGH issues and re-validate until clear
4. Skip validation only for partial snippets, documentation examples, or when user explicitly requests it

Presentation Requirements

See references/validation-presentation.md for detailed requirements on presenting validation results, including status tables, issue explanations, and usage instructions.

---

Best Practices

See references/best-practices.md for the full set of security, performance, reliability, naming, and organization guidelines that all generated pipelines must follow.

---

Anti-Patterns

NEVER use only: [master] or only: [main]

• WHY: only/except are deprecated in GitLab 15+; rules is the current approach and offers more expressive conditions.
• BAD: only: - main
• GOOD: rules: - if: '$CI_COMMIT_BRANCH == "main"'

NEVER deploy to production without an environment and approval gate

• WHY: Deploying directly without a GitLab environment loses deployment tracking, approval workflows, and rollback history.
• BAD: A deployment job with no environment: key.
• GOOD: environment: name: production url: https://example.com combined with when: manual for production jobs.

NEVER hardcode runner tags for every job

• WHY: Hardcoding forces all jobs onto specific runners even when generic runners would work, reducing parallelism.
• BAD: tags: [kubernetes, production] on lint and unit test jobs.
• GOOD: Add runner tags only to jobs that genuinely require specific capabilities (GPU, privileged mode, specific OS).

NEVER define duplicate before_script blocks in every job

• WHY: Repetitive before_script creates maintenance debt; use YAML anchors or extends to share setup.
• BAD: Identical before_script: [npm ci] in every job.
• GOOD: Define a .node_setup hidden job with before_script: [npm ci] and use extends: .node_setup in dependent jobs.

NEVER omit expire_in on artifacts

• WHY: Artifacts without an expiration date are retained indefinitely, consuming storage quota and slowing artifact listing in the GitLab UI.
• BAD: artifacts: paths: [dist/] with no expire_in.
• GOOD: artifacts: paths: [dist/] expire_in: 7 days

References

Reference Files

• references/best-practices.md — Security, performance, pipeline design, anti-patterns
• references/common-patterns.md — Standard patterns (basic CI, Docker, K8s, multi-project)
• references/gitlab-ci-reference.md — Full keyword and syntax reference
• references/security-guidelines.md — Secrets, image, script, and artifact security
• references/validation-presentation.md — Validation results presentation format

Template Files

• assets/templates/basic-pipeline.yml — 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

Template usage: Copy structure → replace [PLACEHOLDERS] → customize logic → remove unused sections → validate.