GitLab CI/CDパイプラインYAML（.gitlab-ci.yml）のフォーマット

GitLab CI/CD YAMLフォーマット

GitLab CI/CDパイプラインはリポジトリルートの .gitlab-ci.yml ファイルで定義されます。このYAMLファイルはステージ、ジョブ、スクリプト、ルール、アーティファクト、キャッシュ — CI/CDワークフロー全体を記述します。

パイプライン構造

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固有のYAML機能

1. 非表示ジョブ — . で始まるジョブはテンプレートであり、実行されない：

   .test-template:
     script:
       - npm test
   

2. extendsキーワード — テンプレートジョブから継承：

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

3. YAMLアンカー — GitLabは再利用のための標準YAMLアンカーをサポートし、extends と併用されることが多い

4. Include — パイプライン設定を複数ファイルに分割：

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

よくあるフォーマットの問題

• script: の下のインデント — スクリプト行はYAMLシーケンスで、各行に - プレフィックスが付く
• 複数行スクリプト — 複雑なスクリプトには複数の - エントリの代わりに | を使用
• rules vs only/except — モダンなGitLab CIは非推奨の only:/except: の代わりに rules: を使用
• 変数展開 — YAML値内の ${VARIABLE} 構文はフォーマッターによって理解される必要がある

バリデーション

GitLabはCI Lintツール（任意のプロジェクトの /ci/lint）を提供しており、YAML構造を検証します。フォーマットしたファイルをCI Lintに通すことで、プッシュ前に構造的なエラーをキャッチできます。