ci-cd

CI/CD パイプライン

GitHub Actions、GitLab CI、その他のプラットフォームにおける CI/CD パイプラインの設計、最適化、セキュリティ、トラブルシューティングに関する包括的なガイドです。

コアワークフロー

1. 新しいパイプラインの作成

判断ツリー：

What are you building?
├── Node.js/Frontend → GitHub: templates/github-actions/node-ci.yml | GitLab: templates/gitlab-ci/node-ci.yml
├── Python → GitHub: templates/github-actions/python-ci.yml | GitLab: templates/gitlab-ci/python-ci.yml
├── Go → GitHub: templates/github-actions/go-ci.yml | GitLab: templates/gitlab-ci/go-ci.yml
├── Docker Image → GitHub: templates/github-actions/docker-build.yml | GitLab: templates/gitlab-ci/docker-build.yml
├── Other → Follow the pipeline design pattern below

基本的なパイプライン構成：

# 1. Fast feedback (lint, format) - <1 min
# 2. Unit tests - 1-5 min
# 3. Integration tests - 5-15 min
# 4. Build artifacts
# 5. E2E tests (optional, main branch only) - 15-30 min
# 6. Deploy (with approval gates)

主な原則（references/best_practices.md より）：

• 迅速に失敗させる：コストの低い検証を最初に実行します
• 並列化する：不要なジョブ依存関係を取り除きます
• 依存関係をキャッシュする：actions/cache または GitLab のキャッシュを使用します（戦略については references/optimization.md を参照）
• アーティファクトを使用する：一度ビルドし、複数回デプロイします
• セキュリティスキャンを早期に追加する：SAST／DAST／SCA の統合については references/devsecops.md を参照してください

2. パイプラインのパフォーマンス最適化

すぐに効果のある改善項目：

• 依存関係のキャッシュを追加する（ビルドを 50～90％高速化）
• 不要な needs 依存関係を取り除く
• パスフィルターを追加して、不要な実行をスキップする
• npm install の代わりに npm ci を使用する
• ハングしたビルドを防ぐため、ジョブのタイムアウトを追加する
• 重複実行をキャンセルする同時実行制御を有効にする

既存のパイプラインを分析する：

# Use the pipeline analyzer script
python3 scripts/pipeline_analyzer.py --platform github --workflow .github/workflows/ci.yml

一般的な最適化（詳細は references/optimization.md を参照）：

• 遅いテスト： マトリックスビルドでテストを分割します
• 依存関係のインストールを繰り返す： キャッシュを追加します
• 順次実行されるジョブ： 適切な needs を設定して並列化します
• すべての PR でテストスイート全体を実行する： パスフィルターまたはテスト影響分析を使用します

詳細なキャッシュ戦略、並列化の手法、パフォーマンスの調整については、optimization.md を参照してください。

3. パイプラインのセキュリティ確保

必須のセキュリティチェックリスト：

• 静的な認証情報の代わりに OIDC を使用する
• アクション／インクルードをコミット SHA に固定する
• 最小限の権限を使用する
• シークレットスキャンを有効にする
• 脆弱性スキャンを追加する（依存関係、コンテナ）
• ブランチ保護を実装する
• テスト用ワークフローとデプロイ用ワークフローを分離する

クイックセットアップ — OIDC 認証：

GitHub Actions → AWS：

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789:role/GitHubActionsRole
      aws-region: us-east-1

シークレット管理：

• プラットフォームのシークレットストア（GitHub Secrets、GitLab CI/CD Variables）に保存します
• GitLab では「masked」として設定します
• 環境ごとにシークレットを使い分けます
• 定期的に（90 日ごとに）ローテーションします
• シークレットをログに出力しないでください

包括的なセキュリティパターン、サプライチェーンセキュリティ、シークレット管理については、security.md を参照してください。

4. パイプライン障害のトラブルシューティング

体系的なアプローチ：

ステップ 1：パイプラインの状態を確認する

gh run list --limit 20    # Recent runs with status (success/failure rates)
gh run view <run-id>      # Detailed run info and failure logs
gh workflow list           # All configured workflows

ステップ 2：障害の種類を特定する

エラーパターン	一般的な原因	すぐにできる対処法
"Module not found"	依存関係の不足またはキャッシュの問題	キャッシュを消去し、npm ci を実行する
"Timeout"	ジョブの実行に時間がかかりすぎている	キャッシュを追加し、タイムアウトを延長する
"Permission denied"	権限の不足	permissions: ブロックに追加する
"Cannot connect to Docker daemon"	Docker が利用できない	適切なランナーまたは DinD を使用する
断続的な障害	不安定なテストまたは競合状態	リトライを追加し、タイミングの問題を修正する

ステップ 3：デバッグログを有効にする

GitHub Actions：

# Add repository secrets:
# ACTIONS_RUNNER_DEBUG = true
# ACTIONS_STEP_DEBUG = true

GitLab CI：

variables:
  CI_DEBUG_TRACE: "true"

ステップ 4：ローカルで再現する

# GitHub Actions - use act
act -j build

# Or Docker
docker run -it ubuntu:latest bash
# Then manually run the failing steps

包括的な問題の診断、プラットフォーム固有の問題、解決策については、troubleshooting.md を参照してください。

5. デプロイワークフローの実装

デプロイパターンの選択：

パターン	ユースケース	複雑さ	リスク
直接デプロイ	シンプルなアプリ、低トラフィック	低	中
ブルーグリーン	ダウンタイムをゼロにする必要がある	中	低
カナリア	段階的なロールアウト、監視	高	非常に低
ローリング	Kubernetes、コンテナ	中	低

基本的なデプロイ構成：

deploy:
  needs: [build, test]
  if: github.ref == 'refs/heads/main'
  environment:
    name: production
    url: https://example.com
  steps:
    - name: Download artifacts
    - name: Deploy
    - name: Health check
    - name: Rollback on failure

マルチ環境の設定：

• 開発： develop ブランチへのプッシュ時に自動デプロイ
• ステージング： main へのプッシュ時に自動デプロイ。テストの合格が必要です
• 本番環境： 手動承認が必要で、スモークテストは必須です

デプロイパターンと環境管理の詳細については、best_practices.md を参照してください。

6. DevSecOps セキュリティスキャンの実装

セキュリティスキャンの種類：

スキャンの種類	目的	実行するタイミング	速度	ツール
シークレットスキャン	漏えいした認証情報を検出します	コミットごと	高速（1 分未満）	TruffleHog, Gitleaks
SAST	コードの脆弱性を検出します	コミットごと	中速（5～15 分）	CodeQL, Semgrep, Bandit, Gosec
SCA	依存関係の脆弱性を検出します	コミットごと	高速（1～5 分）	npm audit, pip-audit, Snyk
コンテナスキャン	イメージの脆弱性を検出します	ビルド後	中速（5～10 分）	Trivy, Grype
DAST	実行時の脆弱性を検出します	スケジュール実行／main のみ	低速（15～60 分）	OWASP ZAP

クイックセットアップ - 既存のパイプラインにセキュリティを追加する：

GitHub Actions：

jobs:
  # Add before build job
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: trufflesecurity/trufflehog@main
      - uses: gitleaks/gitleaks-action@v2

  sast:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: javascript  # or python, go
      - uses: github/codeql-action/analyze@v3

  build:
    needs: [secret-scan, sast]  # Add dependencies

GitLab CI：

stages:
  - security  # Add before other stages
  - build
  - test

# Secret scanning
secret-scan:
  stage: security
  image: trufflesecurity/trufflehog:latest
  script:
    - trufflehog filesystem . --json --fail

# SAST
sast:semgrep:
  stage: security
  image: returntocorp/semgrep
  script:
    - semgrep scan --config=auto .

# Use GitLab templates
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml

包括的なセキュリティパイプラインのテンプレート：

• GitHub Actions： templates/github-actions/security-scan.yml - すべてのスキャン段階を含む完全な DevSecOps パイプライン
• GitLab CI： templates/gitlab-ci/security-scan.yml - GitLab のセキュリティテンプレートを使用した完全な DevSecOps パイプライン

セキュリティゲートのパターン：

すべてのセキュリティスキャン結果を評価し、重大な問題が見つかった場合にパイプラインを失敗させるセキュリティゲートのジョブを追加します。

security-gate:
  needs: [secret-scan, sast, sca, container-scan]
  script:
    # Check for critical vulnerabilities
    # Parse JSON reports and evaluate thresholds
    # Fail if critical issues found

言語固有のセキュリティツール：

• Node.js： CodeQL, Semgrep, npm audit, eslint-plugin-security
• Python： CodeQL, Semgrep, Bandit, pip-audit, Safety
• Go： CodeQL, Semgrep, Gosec, govulncheck

すべての言語固有のテンプレートに、セキュリティスキャンの段階が含まれるようになりました。次を参照してください。

• templates/github-actions/node-ci.yml
• templates/github-actions/python-ci.yml
• templates/github-actions/go-ci.yml
• templates/gitlab-ci/node-ci.yml
• templates/gitlab-ci/python-ci.yml
• templates/gitlab-ci/go-ci.yml

すべてのセキュリティスキャンの種類、ツールの比較、実装パターンを網羅した包括的な DevSecOps ガイドについては、devsecops.md を参照してください。

クイックリファレンスコマンド

GitHub Actions

# List workflows
gh workflow list

# View recent runs
gh run list --limit 20

# View specific run
gh run view <run-id>

# Re-run failed jobs
gh run rerun <run-id> --failed

# Download logs
gh run view <run-id> --log > logs.txt

# Trigger workflow manually
gh workflow run ci.yml

# Check workflow status
gh run watch

GitLab CI

# View pipelines
gl project-pipelines list

# Pipeline status
gl project-pipeline get <pipeline-id>

# Retry failed jobs
gl project-pipeline retry <pipeline-id>

# Cancel pipeline
gl project-pipeline cancel <pipeline-id>

# Download artifacts
gl project-job artifacts <job-id>

プラットフォーム固有のパターン

GitHub Actions

再利用可能なワークフロー：

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}

別のワークフローから呼び出す：

jobs:
  test:
    uses: ./.github/workflows/reusable-test.yml
    with:
      node-version: '20'

GitLab CI

extends を使用するテンプレート：

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

unit-test:
  extends: .test_template
  script:
    - npm run test:unit

integration-test:
  extends: .test_template
  script:
    - npm run test:integration

needs を使用する DAG パイプライン：

build:
  stage: build

test:unit:
  stage: test
  needs: [build]

test:integration:
  stage: test
  needs: [build]

deploy:
  stage: deploy
  needs: [test:unit, test:integration]

診断スクリプト

スクリプト	目的	使用方法
pipeline_analyzer.py	最適化の機会（キャッシュ、並列化、古いアクション）を特定します	python3 scripts/pipeline_analyzer.py --platform github --workflow <path>

パイプラインの健全性チェック（成功／失敗率、失敗パターン）には、gh CLI を使用します：gh run list --limit 20、gh run view <run-id>、gh workflow list。

リファレンスドキュメント

• references/best_practices.md — パイプライン設計、テスト、デプロイのパターン、アーティファクトの処理
• references/security.md — シークレット管理、OIDC、サプライチェーンセキュリティ、安全なパイプラインのパターン
• references/devsecops.md — SAST/DAST/SCA ツール（CodeQL, Semgrep, Trivy, Snyk）、セキュリティゲート
• references/optimization.md — キャッシュ戦略、並列化、テストの分割、ビルドの最適化
• references/troubleshooting.md — よくある問題、Docker の問題、認証、プラットフォームのデバッグ

テンプレート

GitHub Actions と GitLab CI の両方に対応したスターターテンプレートは assets/templates/ にあります。

言語／種類	GitHub Actions	GitLab CI
Node.js	github-actions/node-ci.yml	gitlab-ci/node-ci.yml
Python	github-actions/python-ci.yml	gitlab-ci/python-ci.yml
Go	github-actions/go-ci.yml	gitlab-ci/go-ci.yml
Docker	github-actions/docker-build.yml	gitlab-ci/docker-build.yml
セキュリティ	github-actions/security-scan.yml	gitlab-ci/security-scan.yml

すべてのテンプレートに、セキュリティスキャン、キャッシュ、複数環境へのデプロイが含まれています。

よくあるパターン

依存関係のキャッシュ

GitHub Actions：

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-
- run: npm ci

GitLab CI：

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

マトリックスビルド

GitHub Actions:

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [18, 20, 22]
  fail-fast: false

GitLab CI:

test:
  parallel:
    matrix:
      - NODE_VERSION: ['18', '20', '22']

条件付き実行

GitHub Actions:

- name: Deploy
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'

GitLab CI:

deploy:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual

はじめに

1. 新しいパイプライン： assets/templates/ のテンプレートから始めます
2. セキュリティスキャンの追加： DevSecOps テンプレートを使用するか、既存のパイプラインにセキュリティステージを追加します（上記のワークフロー 6 を参照）
3. 既存のパイプラインの最適化： scripts/pipeline_analyzer.py を実行します
4. 問題のデバッグ： references/troubleshooting.md を確認します
5. セキュリティの強化： references/security.md と references/devsecops.md のチェックリストを確認します
6. ビルドの高速化： references/optimization.md を参照します