Format GitLab CI/CD Pipeline YAML (.gitlab-ci.yml)

GitLab CI/CD YAML Formatting

GitLab CI/CD pipelines are defined in .gitlab-ci.yml files at the repository root. This YAML file describes stages, jobs, scripts, rules, artifacts, and caching — the entire CI/CD workflow.

Pipeline Structure

stages:
  - build
  - test
  - deploy

variables:
  NODE_VERSION: "20"
  DOCKER_REGISTRY: registry.gitlab.com

default:
  image: node:${NODE_VERSION}-alpine
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/

build:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

test:unit:
  stage: test
  script:
    - npm ci
    - npm run test:unit
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'

test:e2e:
  stage: test
  image: cypress/included:latest
  script:
    - npm ci
    - npm run test:e2e
  artifacts:
    when: on_failure
    paths:
      - cypress/screenshots/

deploy:production:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
    url: https://app.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - when: never

GitLab-Specific YAML Features

1. Hidden jobs — Jobs starting with . are templates, not executed:

   .test-template:
     script:
       - npm test
   

2. Extends keyword — Inherit from template jobs:

   test:unit:
     extends: .test-template
     variables:
       TEST_SUITE: unit
   

3. YAML anchors — GitLab supports standard YAML anchors for reuse, and they are commonly used alongside extends

4. Include — Split pipeline config across multiple files:

   include:
     - local: .gitlab/ci/build.yml
     - local: .gitlab/ci/test.yml
     - template: Security/SAST.gitlab-ci.yml
   

Common Formatting Issues

• Indentation under script: — Script lines are a YAML sequence, each prefixed with -
• Multi-line scripts — Use | for complex scripts instead of multiple - entries
• Rules vs. only/except — Modern GitLab CI uses rules: instead of the deprecated only:/except:
• Variable expansion — ${VARIABLE} syntax in YAML values must be understood by the formatter

Validation

GitLab provides a CI Lint tool (/ci/lint in any project) that validates the YAML structure. Running your formatted file through CI Lint catches structural errors before pushing.