CI/CD：GitHub Actions

CI/CD は、自動化されたプロセスを通じてコードの検査、テスト、構築、展開を完了するエンジニアリング プラクティスです。

1. CI および CD

一般的なプロセス:

Developer
    ↓
Git Push / Pull Request
    ↓
GitHub Actions
    │
    ├── Lint / Type Check
    ├── Unit / Integration Tests
    └── Build
           ↓
        CI Passed
           ↓
      Docker Image
           ↓
     Image Registry
           ↓
    Deployment Server
           ↓
    Running Application

CI はコード品質の保証を担当し、CD は配信と展開を担当します。

CI は自動展開を必要としません。最初に CI を実装し、その後 CD を徐々に追加することができます。

2.GitHub Actionsコアモデル

GitHub Actions は、GitHub が提供する自動ワークフロー プラットフォームです。

GitHub Event
     ↓
Workflow
     ↓
Jobs
     ↓
Runner
     ↓
Steps
     ├── uses: Action
     └── run: Shell Command

中心となる概念:

Workflow ファイルは次の場所に保存されます。

.github/
└── workflows/
    ├── ci.yml
    └── deploy.yml

ウェアハウスは複数の Workflow を定義できます。

3. 基本的な Workflow

name: CI

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

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        run: pytest

実行プロセス:

Push to main / PR to main
             ↓
      Start Workflow
             ↓
   Create Ubuntu Runner
             ↓
      Checkout Code
             ↓
      Install Python
             ↓
   Install Dependencies
             ↓
          pytest
             ↓
       Pass / Fail

ここでは、プロジェクトの依存関係とテスト環境が正しく構成されていることを前提としています。 Django が PostgreSQL を使用する場合は、テスト データベース サービスも提供する必要があります。

重要な YAML フィールド

uses と run の違い:

- uses: actions/checkout@v4

すでに実装されている Action を呼び出します。

- run: pytest

コマンドを直接実行します。

4. Event: Workflow トリガー条件

Push

on:
  push:
    branches: [main]

タグが main にプッシュされるたびに起動されます。

Pull Request

on:
  pull_request:
    branches: [main]

ターゲットが main である PR が作成または更新されるときにトリガーされます。

手動トリガー

on:
  workflow_dispatch:

GitHub Actions ページで手動で実行できます。

Tag / Release

on:
  push:
    tags:
      - "v*"

たとえば、v1.2.0 がプッシュされたときに公開します。

スケジュールされたタスク

on:
  schedule:
    - cron: "0 2 * * *"

UTC 時間を使用すると、毎日 02:00 に起動するようにスケジュールされます。 Workflow のタイミングは遅れる可能性があり、厳密に時間通りであることは保証されません。

5. Job、Step、Runner

Workflow には複数の Job を含めることができます。

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Testing"

  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building"

デフォルトでは、異なる Job を並行して実行できます。

同じ Job 内の Steps は通常、連続して実行されます。

needs: Job 依存関係

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: pytest

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: docker build -t myapp .

build を実行する前に、test が最初に完了する必要があり、通常は成功する必要があることを示します。

Test
  ↓
Build
  ↓
Deploy

Job 絶縁

通常、各 GitHub-hosted Runner 上の Job は別の環境で実行されます。

したがって、Job とは異なり、ローカル ファイルは自動的に共有されません。

ビルド製品を納品する必要がある場合は、Artifact またはミラー ウェアハウスを使用できます。

6. 実際の CI: Django + React

フロントエンドとバックエンドの分離プロジェクトの場合、それぞれ Backend と Frontend Job を定義できます。

name: CI

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

permissions:
  contents: read

jobs:
  backend:
    runs-on: ubuntu-latest

    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

      - name: Run tests
        run: pytest

      - name: Validate OpenAPI
        run: >
          python manage.py spectacular
          --file openapi.yaml
          --validate
          --fail-on-warn

  frontend:
    runs-on: ubuntu-latest

    defaults:
      run:
        working-directory: frontend

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: pnpm
          cache-dependency-path: frontend/pnpm-lock.yaml

      - run: corepack enable

      - run: pnpm install --frozen-lockfile

      - name: Type Check
        run: pnpm exec tsc -b

      - name: Build
        run: pnpm build

これは簡略化した例です。実際の使用方法は、ディレクトリ構造、データベース、環境変数に応じて調整する必要があります。特に、pytest が PostgreSQL に依存している場合、services またはその他のテスト データベース構成を追加する必要があります。

また、フロントエンド Orval の生成コードは最新の OpenAPI Schema と一致する必要があり、CI に生成結果のチェックを追加できます。

一般的な CI チェック

最初にすべてのチェックを有効にする必要はありません。 pytest、TypeScript、および実稼働ビルドが安定して通過できることを確認することをお勧めします。

7. CacheとArtifact

Cache: ビルドを高速化します

たとえば:

- uses: actions/setup-node@v4
  with:
    node-version: "24"
    cache: pnpm

パッケージ マネージャーによってダウンロードされた依存関係をキャッシュして、後続の Workflow を高速化できます。

以下もご利用いただけます:

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ runner.os }}-${{ hashFiles('requirements.txt') }}

注: Cache はパフォーマンスの最適化に使用され、正しいビルドを保証するためにキャッシュの存在に依存すべきではありません。

Artifact: ビルド結果の保存

たとえば:

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

保存可能:

• フロントエンドのビルド結果。
• テストレポート。
• Coverageレポート。
• その他のビルド製品。

違い:

8. Secrets、Variables、Contexts

Secrets

GitHub リポジトリ内:

Settings
  ↓
Secrets and variables
  ↓
Actions

設定可能:

DEPLOY_HOST
DEPLOY_USER
SSH_PRIVATE_KEY

Workflow は次のように読み取ります。

env:
  DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}

Secrets は、Token、SSH Private Key などのパスワードに適しています。

Variables

非機密構成では Variables を使用できます。

env:
  APP_ENV: ${{ vars.APP_ENV }}

Contexts

GitHub Actions は組み込みコンテキストを提供します。

${{ github.ref }}
${{ github.sha }}
${{ github.actor }}
${{ github.repository }}
${{ github.event_name }}
${{ secrets.MY_SECRET }}
${{ vars.APP_ENV }}

${{ ... }} は GitHub Actions の式構文であり、Bash の変数構文ではありません。

そして:

$APP_ENV

通常は Shell 環境変数です。

GITHUB_TOKEN

GitHub は、GitHub API および一部のウェアハウス リソースにアクセスするための一時的な GITHUB_TOKEN を Workflow に提供します。

最小特権の原則に従うことをお勧めします。

permissions:
  contents: read

GHCR イメージをプッシュする必要がある場合:

permissions:
  contents: read
  packages: write

9. CD: Docker ミラーリリース

Docker Compose 導入の場合、共通の CD プロセス:

Merge to main
      ↓
CI Pass
      ↓
Docker Build
      ↓
Push Image to GHCR
      ↓
VPS Pull Image
      ↓
Docker Compose Up
      ↓
Health Check

GHCR

GitHub Container Registry：

ghcr.io/username/sorivel-backend:1.2.0

GitHub Actions を使用して、Docker イメージを構築してプッシュできます。

例:

name: Publish Backend

on:
  push:
    tags:
      - "v*"

permissions:
  contents: read
  packages: write

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

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

      - uses: docker/build-push-action@v6
        with:
          context: ./backend
          push: true
          tags: ghcr.io/your-org/sorivel-backend:${{ github.ref_name }}

ここでは、your-org を置き換えて、イメージの名前付けと公開権限が正しいことを確認する必要があります。テストに失敗したコードがリリースされるのを避けるために、Workflow のリリースは実際には CI の成功条件に関連付けられる必要があります。

VPS展開

サーバー Compose はミラーリングを使用します。

services:
  backend:
    image: ghcr.io/your-org/sorivel-backend:v1.2.0
    restart: unless-stopped

更新:

docker compose pull backend
docker compose up -d backend

この方法では、イメージ ビルドは毎回 VPS でリビルドするのではなく、GitHub Actions に配置されます。

より複雑な自動展開は、SSH、Self-hosted Runner、またはその他の展開システムを通じて実現できますが、信頼できない PR コードを運用サーバーで直接実行することはお勧めできません。

10. Environment と展開保護

GitHub ActionsはDeployment Environmentをサポートします。

たとえば:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

Production 環境用に構成できます。

• 環境グレードSecrets。
• 環境グレードVariables。
• 承認ルール。
• ブランチまたは Tag 制限。

一部の保護機能は、倉庫のタイプと GitHub Plan によって異なります。

運用環境のデプロイでは、以下を区別することをお勧めします。

Development
Staging（オプション）
Production

VPS が 1 つしかない場合でも、Production Environment を使用して展開資格情報と公開権限を管理できます。

11. Concurrency: 同時デプロイメントの防止

concurrency:
  group: production-deploy
  cancel-in-progress: false

同じ Concurrency Group で複数のデプロイメントが同時に実行されていないことを確認してください。

cancel-in-progress: false は、すでに実行中のデプロイメントを積極的にキャンセルしないことを意味しますが、新しくトリガーされた Pending Run が古い Pending Run を置き換える可能性はあります。厳密な FIFO デプロイメント キューは提供されません。

CI の場合、次を使用できます。

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

新しい送信により、同じブランチ上の古い未完了の CI をキャンセルできるため、リソースの無駄が削減されます。

12. CI/CD セキュリティとロールバック

安全原則

1. 最小特権 GITHUB_TOKEN を使用します。
2. Secrets はリポジトリまたは Dockerfile に書き込みません。
3. 信頼できない PR が運用環境の資格情報にアクセスできないようにします。
4. サプライチェーンのセキュリティを向上させるために、サードパーティの Actions が最初に修正され、Commit SHA が完成します。
5. PR で信頼できないコードを実行するために、高い特権 Token を持つ pull_request_target を恣意的に使用しないでください。
6. 導入前に必要なテストとビルド チェックを実行します。

ロールバック (Rollback)

latest タグのみに依存しないでください。

明示的なバージョンを使用することをお勧めします。

sorivel-backend:v1.2.0
sorivel-backend:v1.2.1

新しいバージョンに問題がある場合:

Current: v1.2.1
      ↓
Rollback
      ↓
Previous: v1.2.0

イメージのバージョンを変更して再デプロイします。

docker compose pull backend
docker compose up -d backend

また、アプリケーション ミラー ロールバックはデータベース ロールバックと同じではないことに注意してください。 デプロイメントで破壊的な Migration も実行される場合は、データベースの互換性と回復戦略を個別に設計する必要があります。

13. CI/CD の推奨プラクティス

1 つの VPS + Docker Compose プロジェクトでは、3 つのフェーズを採用できます。

フェーズ 1: CI

PR / Push
   ↓
pytest
   ↓
Type Check
   ↓
Build

目標: コードが信頼できるかどうかを自動的にチェックします。

フェーズ 2: 画像を自動的に公開する

Main / Release Tag
       ↓
CI Passed
       ↓
Docker Build
       ↓
Push to GHCR

目標: イメージの展開可能で追跡可能なバージョンを構築します。

フェーズ 3: 自動展開

Approved Release
       ↓
Deploy to VPS
       ↓
docker compose pull
       ↓
docker compose up -d
       ↓
Health Check

目標: デプロイメントを反復可能、検証可能、ロール可能にする。

概要

GitHub Actions 最も重要な概念:

GitHub Actions の中心的な機能は、特定のイベントが発生したときに、Runner で事前定義されたワークフローを自動的に実行することです。

日々の開発では、以下を習得することを優先してください。

1. Push / PR に基づいて Workflow をトリガーする方法。
2. 複数の Job を含む YAML の書き方。
3. pytest、TypeScript、Vite ビルドを実行する方法。
4. Cache、Secrets、環境変数の使い方。
5. Docker イメージをビルドして GHCR に公開する方法。
6. VPS でのデプロイとロールバックの方法。

---

参考資料

• GitHub Actions 公式ドキュメント
• Workflow Syntax
• Workflow Concepts
• Publishing Docker Images
• Security in GitHub Actions