メインコンテンツまでスキップ

GitHub ActionsとWorkflowの基礎

GitHub Actionsは、GitHubリポジトリ内で直接ソフトウェア開発ワークフローを自動化するためのCI/CD（継続的インテグレーション/継続的デリバリー）プラットフォームです。

概要​

GitHub Actionsを使用すると、コードのビルド、テスト、デプロイを自動化できます。プルリクエストやissueの作成など、GitHub上のイベントをトリガーとしてワークフローを実行することが可能です。

主要な概念​

GitHub Actionsを理解するための重要な用語を解説します。

1. Workflow (ワークフロー)​

1つ以上のジョブを実行する構成可能な自動化プロセスです。YAMLファイルとして定義され、リポジトリの .github/workflows ディレクトリに保存されます。

2. Event (イベント)​

ワークフローの実行をトリガーする特定のアクティビティです。

  • push: コードがプッシュされたとき
  • pull_request: プルリクエストが作成・更新されたとき
  • schedule: 定期的なスケジュール実行
  • workflow_dispatch: 手動実行

3. Job (ジョブ)​

同じランナー上で実行される一連のステップです。デフォルトでは、複数のジョブは並列に実行されますが、依存関係を定義して順次実行することも可能です。

4. Step (ステップ)​

ジョブ内で実行される個々のアクションやシェルコマンドです。同じジョブ内のステップはデータを共有できます。

5. Action (アクション)​

ワークフロー内で使用できる再利用可能なコマンドの最小単位です。独自に作成することも、GitHub Marketplaceで公開されているアクションを使用することもできます。

6. Runner (ランナー)​

ワークフローが実行されるサーバーです。GitHubがホストするランナー（Ubuntu, Windows, macOS）や、自分でホストするセルフホストランナーが利用できます。

Workflowファイルの構造​

基本的なWorkflowファイルの構造は以下のようになります。

.github/workflows/example.yml
name: CI Example

# トリガーとなるイベントの定義
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

# 実行するジョブの定義
jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      # リポジトリのコードをチェックアウト
      - name: Checkout code
        uses: actions/checkout@v4

      # Node.jsのセットアップ
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      # 依存関係のインストール
      - name: Install dependencies
        run: npm ci

      # テストの実行
      - name: Run tests
        run: npm test

      # ビルドの実行
      - name: Build
        run: npm run build

実践的な使用例​

複数のOSでのテスト (Matrix Strategy)​

異なる環境でテストを実行したい場合、strategy.matrixを使用すると便利です。

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18.x, 20.x]

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

成果物の保存 (Artifacts)​

ビルド生成物やログなどを保存して、ワークフロー完了後にダウンロードできるようにするには actions/upload-artifact を使用します。

      - name: Build
        run: npm run build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist-files
          path: dist/

ベストプラクティス​

  1. アクションのバージョン固定: サードパーティのアクションを使用する場合は、予期せぬ変更を防ぐためにバージョンタグ（例: @v4）やコミットハッシュを指定しましょう。
  2. シークレットの管理: APIキーやパスワードなどの機密情報は、リポジトリの Settings > Secrets and variables に保存し、${{ secrets.MY_SECRET }} のように参照します。
  3. キャッシュの活用: actions/cache や setup-node のキャッシュ機能を使用して、依存関係のインストール時間を短縮しましょう。
  4. 不要な実行の抑制: パスのフィルタリング（paths-ignore）を使用して、ドキュメントの変更のみの場合はCIをスキップするなどの設定を行うと、リソースを節約できます。
on:
  push:
    paths-ignore:
      - 'docs/**'
      - '*.md'