ci-cd-ops

CI/CD 運用

GitHub Actions、リリース自動化ツール、テストパイプラインを使った継続的インテグレーション、継続的デリバリー、継続的デプロイの包括的なパターンです。

GitHub Actions クイックリファレンス

ワークフローファイルの構成

name: CI                          # Display name in Actions tab
on:                               # Trigger events
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:                      # GITHUB_TOKEN scope (least privilege)
  contents: read
  pull-requests: write

concurrency:                      # Prevent duplicate runs
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:                              # Workflow-level environment variables
  NODE_VERSION: "20"

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      - run: npm test

主な構文要素

要素	目的	例
on	イベントのトリガー	push、pull_request、schedule
jobs.<id>.runs-on	ランナーの選択	ubuntu-latest、self-hosted
jobs.<id>.needs	ジョブの依存関係	needs: [build, lint]
jobs.<id>.if	条件付き実行	if: github.event_name == 'push'
jobs.<id>.strategy.matrix	並列実行するバリエーション	node-version: [18, 20, 22]
jobs.<id>.environment	デプロイ先	environment: production
jobs.<id>.permissions	トークンの権限範囲	contents: write
steps[*].uses	アクションを使用	uses: actions/checkout@v4
steps[*].run	コマンドを実行	run: npm test
steps[*].env	ステップの環境変数	env: { CI: true }

トリガー選択ツリー

シナリオ	トリガー	設定
すべての PR でテストを実行	pull_request	branches: [main]
main へのマージ時にデプロイ	push	branches: [main]
バージョンタグでリリース	push	tags: ['v*']
夜間ビルド	schedule	cron: '0 2 * * *'
手動デプロイ	workflow_dispatch	inputs: { environment: ... }
別のワークフローから呼び出し	workflow_call	inputs:、secrets:
PR ラベルの変更時	pull_request	types: [labeled]
Issue コメント時	issue_comment	types: [created]
リリース公開時	release	types: [published]
パッケージのプッシュ時	registry_package	types: [published]

トリガーフィルターのパターン

on:
  push:
    branches: [main, 'release/**']      # Branch patterns
    paths: ['src/**', '!src/**/*.test.*'] # Path filters (ignore tests)
    tags: ['v*']                          # Tag patterns
  pull_request:
    types: [opened, synchronize, reopened] # Default types
    paths-ignore: ['docs/**', '*.md']     # Ignore docs-only changes

キャッシュ戦略

エコシステム	アクション／キー	パス	復元キー
Node（npm）	cache: npm を指定した actions/setup-node	自動	自動
Node（pnpm）	cache: pnpm を指定した actions/setup-node	自動	自動
Go モジュール	cache: true を指定した actions/setup-go	自動	自動
Cargo	actions/cache@v4	~/.cargo/registry、target	cargo-${{ runner.os }}-${{ hashFiles('Cargo.lock') }}
pip／uv	cache: pip を指定した actions/setup-python	自動	自動
Docker レイヤー	docker/build-push-action	buildx キャッシュを使用	type=gha または type=registry
Gradle	cache: gradle を指定した actions/setup-java	自動	自動
Composer	actions/cache@v4	vendor	composer-${{ hashFiles('composer.lock') }}

手動キャッシュの例

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/bin
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
    restore-keys: |
      cargo-${{ runner.os }}-

マトリックス戦略

strategy:
  fail-fast: false                    # Don't cancel siblings on failure
  max-parallel: 4                     # Limit concurrent jobs
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node-version: [18, 20, 22]
    include:                          # Add specific combos
      - os: ubuntu-latest
        node-version: 22
        coverage: true
    exclude:                          # Remove specific combos
      - os: windows-latest
        node-version: 18

動的マトリックス

prepare:
  runs-on: ubuntu-latest
  outputs:
    matrix: ${{ steps.set.outputs.matrix }}
  steps:
    - id: set
      run: echo "matrix=$(jq -c . matrix.json)" >> "$GITHUB_OUTPUT"

test:
  needs: prepare
  strategy:
    matrix: ${{ fromJson(needs.prepare.outputs.matrix) }}

シークレット管理

スコープ	アクセス範囲	用途
リポジトリシークレット	リポジトリ内のすべてのワークフロー	API キー、トークン
環境シークレット	対象の環境を指定したジョブ	本番環境の認証情報
組織シークレット	組織内で選択したリポジトリ	共有サービスアカウント
OIDC トークン	フェデレーション ID	クラウドへのデプロイ（シークレットの保存不要）

シークレット管理のベストプラクティス

# Reference secrets - NEVER echo or log them
- run: deploy --token ${{ secrets.DEPLOY_TOKEN }}

# Mask custom values
- run: echo "::add-mask::$CUSTOM_SECRET"

# Use environments for deployment secrets
jobs:
  deploy:
    environment: production           # Requires approval + has secrets
    steps:
      - run: deploy --key ${{ secrets.PROD_API_KEY }}

クラウド向け OIDC（シークレットの保存不要）

permissions:
  id-token: write
  contents: read

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

よくあるワークフローパターン

プルリクエストでテストを実行

name: Test
on:
  pull_request:
    branches: [main]
concurrency:
  group: test-${{ github.head_ref }}
  cancel-in-progress: true
jobs:
  test:
    runs-on: ubuntu-latest
    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

main へのマージ時にデプロイ

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

タグでリリース

name: Release
on:
  push:
    tags: ['v*']
permissions:
  contents: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: |
          gh release create ${{ github.ref_name }} \
            --generate-notes \
            --title "${{ github.ref_name }}"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

よくある落とし穴

落とし穴	問題	解決策
浅いクローン	git describe が失敗し、履歴が不足します	fetch-depth: 0 を指定して actions/checkout@v4 を使用します
デフォルトの権限	GITHUB_TOKEN はデフォルトで読み取り専用です	permissions: を明示的に設定します
アクションのピン留め	@main は警告なしに動作しなくなる場合があります	SHA（@abc123 または @v4）にピン留めします
フォークからの PR のシークレット	フォークからの PR ではシークレットを利用できません	pull_request_target を慎重に使用します
同時デプロイ	本番環境で競合状態が発生します	concurrency: グループを使用します
古いキャッシュ	キャッシュが際限なく増加します	キーにロックファイルのハッシュを含めます
Node.js のバージョン	setup-node のデフォルト値は環境によって異なります	常に node-version を指定します
Docker レイヤーキャッシュ	キャッシュなしではすべてを再ビルドします	cache-from: type=gha を使用します
マトリックスと環境	マトリックスの各ジョブで承認が必要です	マトリックスの後に単一のデプロイジョブを使用します
パスフィルターと必須チェック	スキップされたジョブによってマージがブロックされます	paths-filter アクションを使用するか、チェックを必須にしないようにします
PR 内の GITHUB_TOKEN	他のワークフローをトリガーできません	PAT または GitHub App トークンを使用します
Windows の改行コード	スクリプトが \r\n で失敗します	.gitattributes または core.autocrlf を使用します

式構文のクイックリファレンス

式	結果
${{ github.event_name }}	push、pull_request など
${{ github.ref_name }}	ブランチ名またはタグ名
${{ github.sha }}	完全なコミット SHA
${{ github.actor }}	トリガーしたユーザー
${{ runner.os }}	Linux、Windows、macOS
${{ contains(github.event.head_commit.message, '[skip ci]') }}	コミットメッセージを確認します
${{ needs.build.outputs.version }}	前のジョブからの出力
${{ fromJson(steps.meta.outputs.json) }}	JSON 出力を解析します
${{ hashFiles('**/package-lock.json') }}	キャッシュキー用のハッシュ
${{ format('refs/heads/{0}', matrix.branch) }}	文字列の書式設定
${{ toJson(matrix) }}	デバッグ：マトリックス設定を出力します

ステップの出力

steps:
  - id: version
    run: echo "value=$(cat VERSION)" >> "$GITHUB_OUTPUT"

  - run: echo "Version is ${{ steps.version.outputs.value }}"

ジョブの出力（ジョブ間の通信）

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-id: ${{ steps.upload.outputs.artifact-id }}
    steps:
      - id: upload
        run: echo "artifact-id=abc123" >> "$GITHUB_OUTPUT"

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying ${{ needs.build.outputs.artifact-id }}"

リファレンスファイル

ファイル	内容
references/github-actions.md	ワークフロー構文、再利用可能なワークフロー、コンポジットアクション、OIDC、ランナー、デバッグの全般
references/release-automation.md	セマンティックバージョニング、semantic-release、changesets、goreleaser、変更履歴、公開
references/testing-pipelines.md	テスト段階、並列化、カバレッジ、サービスコンテナ、CI での E2E、デプロイパイプライン