gitlab-ci

GitLab CI/CD

GitLab に統合された CI/CD システムで、ソフトウェアのデリバリーパイプラインを自動化します。

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• GitLab で CI/CD パイプラインを設定する
• GitLab ランナー（共有またはセルフホスト）を設定する
• マルチステージのデプロイパイプラインを作成する
• GitLab Auto DevOps を実装する
• CI/CD 変数とシークレットを管理する

前提条件

• GitLab リポジトリ（gitlab.com またはセルフホスト）
• YAML の基本的な理解
• セルフホストランナーの場合：Linux サーバーまたは Kubernetes クラスター

パイプラインの設定

リポジトリのルートに .gitlab-ci.yml を作成します。

stages:
  - build
  - test
  - deploy

variables:
  NODE_VERSION: "20"

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm test
  coverage: '/Coverage: \d+\.\d+%/'

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
    url: https://example.com
  only:
    - main

ジョブの設定

ルールベースの実行

deploy:
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - when: on_success

並列ジョブ

test:
  stage: test
  parallel: 3
  script:
    - npm test -- --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

マトリックスビルド

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

キャッシュ

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
  policy: pull-push

build:
  cache:
    key: build-cache
    paths:
      - .cache/
    policy: pull

アーティファクト

build:
  artifacts:
    paths:
      - dist/
      - coverage/
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura.xml
    expire_in: 1 week
    when: always

環境とデプロイ

deploy_staging:
  stage: deploy
  script:
    - deploy --env staging
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop_staging

stop_staging:
  stage: deploy
  script:
    - undeploy --env staging
  environment:
    name: staging
    action: stop
  when: manual

Docker ビルド

build_image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

GitLab ランナー

ランナーのインストール

# Download and install
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt install gitlab-runner

# Register runner
sudo gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token TOKEN \
  --executor docker \
  --docker-image alpine:latest

ランナーの設定

# /etc/gitlab-runner/config.toml
[[runners]]
  name = "docker-runner"
  url = "https://gitlab.com/"
  token = "TOKEN"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = true
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]

ランナーのタグ

build:
  tags:
    - docker
    - linux
  script:
    - make build

CI/CD 変数

保護された変数

Settings > CI/CD > Variables で定義します。

• AWS_ACCESS_KEY_ID（保護、マスク済み）
• AWS_SECRET_ACCESS_KEY（保護、マスク済み）

変数の使用

deploy:
  script:
    - aws s3 sync dist/ s3://$S3_BUCKET
  variables:
    AWS_DEFAULT_REGION: us-east-1

インクルードと拡張

テンプレートのインクルード

include:
  - template: Security/SAST.gitlab-ci.yml
  - project: 'group/shared-ci'
    file: '/templates/deploy.yml'
  - local: '/ci/jobs.yml'

ジョブの拡張

.base_job:
  image: node:20
  before_script:
    - npm ci

build:
  extends: .base_job
  script:
    - npm run build

test:
  extends: .base_job
  script:
    - npm test

マルチプロジェクトパイプライン

trigger_downstream:
  stage: deploy
  trigger:
    project: group/downstream-project
    branch: main
    strategy: depend

よくある問題

問題：パイプラインが停止する

問題：ジョブが保留状態のままになる
解決策：ランナーが利用可能かどうか、およびタグが一致しているかを確認します。

問題：Docker-in-Docker が失敗する

問題：Docker デーモンに接続できない
解決策：適切な TLS 設定で docker:dind サービスを使用します。

問題：キャッシュが機能しない

問題：ジョブ間でキャッシュが見つからない
解決策：キャッシュキーを確認し、ランナーが分散キャッシュを共有していることを確認します。

ベストプラクティス

• 複雑な条件には only/except ではなく rules を使用します
• GitLab に組み込まれたセキュリティスキャンテンプレートを活用します
• ジョブの依存関係を使用してパイプラインの速度を最適化します
• マージリクエスト向けにレビューアプリを実装します
• 依存関係を積極的にキャッシュします
• ステージ間でデータを渡すにはアーティファクトを使用します

関連スキル

• github-actions - GitHub の CI/CD 代替手段
• argocd-gitops - GitOps デプロイ
• container-registries - レジストリ管理