pipeline-blueprint

CI/CD 設定のベストプラクティス

このスキルでは、GitHub Actions と GitLab CI 向けの CI/CD パイプラインテンプレートとベストプラクティスを紹介します。プロジェクトの種類に応じた設定を推奨し、信頼性、安全性、効率性の高いパイプラインをチームがすばやく構築できるようにします。

使用方法

ユーザーがプロジェクト（言語、フレームワーク、デプロイ先）について説明したら、以下から最も適切なパイプラインテンプレートを推奨します。ステージ、キャッシュ戦略、デプロイ手順は、ユーザーの技術スタックに合わせて調整してください。

---

一般的なベストプラクティス

パイプライン設計の原則

1. 早期に失敗させる：負荷の高い統合テストや E2E テストの前に、リンティングとユニットテストを実行します。
2. 積極的にキャッシュする：依存関係のディレクトリ（node_modules、.pip_cache、.m2、.gradle）をキャッシュして、ビルドを高速化します。
3. バージョンを固定する：CI ランナーのイメージ、ツール、アクションのバージョンは SHA または正確なタグで固定し、latest は使用しないでください。
4. 最小権限の原則：トークンと認証情報には最小限の権限を設定します。対応している場合は、長期間有効なシークレットより OIDC を優先してください。
5. 並列化する：テストスイートを複数の並列ジョブに分割します。複数バージョンのテストにはマトリックスビルドを使用します。
6. 不変のアーティファクト：一度ビルドしたアーティファクトを、ステージングから本番環境へ同じものを昇格させます。
7. ブランチ保護：マージ前に CI の成功を必須にします。デフォルトブランチにはステータスチェックを設定します。

セキュリティチェックリスト

• パイプラインファイルにシークレットをハードコードしないでください。プラットフォームのシークレット管理（GitHub Secrets / GitLab CI Variables）を使用します。
• サードパーティのアクションやイメージは、使用前に監査します。公式または検証済みのソースを優先してください。
• 可能な場合は、依存関係スキャン（Dependabot、GitLab Dependency Scanning）と SAST を有効にします。
• 本番環境へのデプロイをトリガーできるユーザーを制限します。
• シークレットは定期的にローテーションします。

---

プロジェクトの種類別テンプレート

1. フロントエンド（React / Vue / Angular / 静的サイト）

主なステージ：インストール → リント → テスト → ビルド → デプロイ

GitHub Actions

name: Frontend CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  ci:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci

      - run: npm run lint

      - run: npm test -- --coverage

      - run: npm run build

      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy:
    needs: ci
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-22.04
    environment: production
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      # Replace with your deployment step (e.g., S3 sync, Cloudflare Pages, Vercel)
      - name: Deploy
        run: echo "Add your deployment command here"

GitLab CI

stages:
  - install
  - lint
  - test
  - build
  - deploy

default:
  image: node:20-slim
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

install:
  stage: install
  script:
    - npm ci

lint:
  stage: lint
  script:
    - npm run lint

test:
  stage: test
  script:
    - npm test -- --coverage
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

deploy:
  stage: deploy
  script:
    - echo "Add your deployment command here"
  environment:
    name: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: on_success

---

2. バックエンド（Node.js / Python / Go / Java）

主なステージ：インストール → リント → テスト → ビルド → Docker ビルド → デプロイ

GitHub Actions（Python の例）

name: Backend CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  packages: write

jobs:
  ci:
    runs-on: ubuntu-22.04
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - run: pip install -r requirements.txt

      - run: ruff check .

      - run: pytest --cov --cov-report=xml
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/testdb

  docker:
    needs: ci
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

GitLab CI（Python の例）

stages:
  - test
  - build
  - deploy

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip_cache"

default:
  image: python:3.12-slim

test:
  stage: test
  services:
    - postgres:16
  variables:
    POSTGRES_USER: test
    POSTGRES_PASSWORD: test
    POSTGRES_DB: testdb
    DATABASE_URL: postgresql://test:test@postgres:5432/testdb
  cache:
    key: pip
    paths:
      - .pip_cache/
  script:
    - pip install -r requirements.txt
    - ruff check .
    - pytest --cov --cov-report=xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

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
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy:
  stage: deploy
  script:
    - echo "Add your deployment command here"
  environment:
    name: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

---

3. ライブラリ / パッケージ（npm / PyPI / Maven）

主なステージ：リント → テスト（マトリックス）→ ビルド → 公開

GitHub Actions（npm ライブラリの例）

name: Library CI/CD

on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  test:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - run: npm ci
      - run: npm run lint
      - run: npm test

  publish:
    needs: test
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
          cache: npm

      - run: npm ci
      - run: npm run build
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

GitLab CI（PyPI ライブラリの例）

stages:
  - test
  - publish

test:
  stage: test
  image: python:${PYTHON_VERSION}-slim
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.10", "3.11", "3.12"]
  script:
    - pip install -e ".[dev]"
    - ruff check .
    - pytest

publish:
  stage: publish
  image: python:3.12-slim
  script:
    - pip install build twine
    - python -m build
    - twine upload dist/*
  variables:
    TWINE_USERNAME: __token__
    TWINE_PASSWORD: $PYPI_TOKEN
  rules:
    - if: $CI_COMMIT_TAG =~ /^v/

---

4. フルスタック（フロントエンド + バックエンドのモノレポ）

主なステージ：変更を検出 → 影響を受けるパイプラインを実行 → 統合テスト → デプロイ

GitHub Actions

name: Fullstack CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  changes:
    runs-on: ubuntu-22.04
    outputs:
      frontend: ${{ steps.filter.outputs.frontend }}
      backend: ${{ steps.filter.outputs.backend }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            frontend:
              - 'frontend/**'
            backend:
              - 'backend/**'

  frontend:
    needs: changes
    if: needs.changes.outputs.frontend == 'true'
    runs-on: ubuntu-22.04
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

  backend:
    needs: changes
    if: needs.changes.outputs.backend == 'true'
    runs-on: ubuntu-22.04
    defaults:
      run:
        working-directory: backend
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
          cache-dependency-path: backend/requirements.txt
      - run: pip install -r requirements.txt
      - run: ruff check .
      - run: pytest

  e2e:
    needs: [frontend, backend]
    if: always() && !cancelled() && !contains(needs.*.result, 'failure')
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: Run E2E tests
        run: echo "Add E2E test command (e.g., Playwright, Cypress)"

---

5. モノレポ（Turborepo / Nx / Lerna）

GitHub Actions（Turborepo の例）

name: Monorepo CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  ci:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci

      - run: npx turbo run lint test build --filter='...[HEAD^]'
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

---

6. モバイル（React Native / Flutter）

GitHub Actions（React Native / Android の例）

name: Mobile CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run lint
      - run: npm test

  android-build:
    needs: test
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17
          cache: gradle

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci

      - name: Build Android
        working-directory: android
        run: ./gradlew assembleRelease

      - uses: actions/upload-artifact@v4
        with:
          name: android-apk
          path: android/app/build/outputs/apk/release/*.apk

---

高度なパターン

再利用可能なワークフロー（GitHub Actions）

共通の CI ロジックを再利用可能なワークフローに切り出すことで、リポジトリ間の重複を減らせます。

# .github/workflows/reusable-node-ci.yml
name: Reusable Node CI

on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: "20"
      working-directory:
        type: string
        default: "."

jobs:
  ci:
    runs-on: ubuntu-22.04
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

GitLab CI の Include テンプレート

# Use shared templates to standardize pipelines across projects
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - project: 'my-org/ci-templates'
    ref: main
    file: '/templates/node-ci.yml'

環境の保護ルール

• GitHub：本番環境へのデプロイには、必須レビュー担当者を指定した環境保護ルールを使用します。
• GitLab：承認が必要なデプロイには、when: manual と allow_failure: false を使用します。

キャッシュ戦略の概要

エコシステム	キャッシュキー	キャッシュパス
Node (npm)	package-lock.json	~/.npm または node_modules/
Python	requirements.txt	~/.cache/pip
Go	go.sum	~/go/pkg/mod
Java	build.gradle / pom.xml	~/.gradle/caches / ~/.m2
Rust	Cargo.lock	~/.cargo および target/

---

判断ガイド：使用するテンプレート

プロジェクトの種類…	推奨テンプレート
シングルページアプリ、静的サイト、または SSR フロントエンド	フロントエンド
REST API、マイクロサービス、またはサーバーアプリ	バックエンド
他の人がインストールする npm/PyPI/Maven パッケージ	ライブラリ
1 つのリポジトリにフロントエンドとバックエンドがある	フルスタック
Turborepo/Nx/Lerna で管理する複数のパッケージ	モノレポ
React Native または Flutter アプリ	モバイル