PR

GitHub Actionsのワークフローファイル作成入門：YAML基礎から実践まで

GitHub Actionsを使って開発プロセスを自動化したいけれど、「ワークフローファイルってどう作るの？」と悩んでいませんか？この記事では、GitHub Actionsの心臓部であるワークフローファイルの作成方法を、初心者でも分かるよう丁寧に解説します。

参考記事：GitHub Actionsとは？CI/CDを自動化する開発者必須ツールの完全ガイド

ワークフローファイルとは

ワークフローファイルは、GitHub Actionsで「いつ」「何を」実行するかを定義するYAML形式のファイルです。このファイルによって、コードのプッシュ時にテストを実行したり、プルリクエスト作成時に自動チェックを行ったりできます。

ワークフローファイルの役割

  • トリガー定義：どのイベントで実行するか
  • 実行環境指定：どのOSで動かすか
  • 処理内容定義：具体的に何をするか
  • 条件分岐：特定の条件下でのみ実行する処理

ディレクトリ構造の準備

ワークフローファイルは、リポジトリの特定の場所に配置する必要があります。

必要なディレクトリ構造

your-repository/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       ├── deploy.yml
│       └── tests.yml
├── src/
└── README.md

ディレクトリ作成手順

1. GitHubのWebインターフェースで作成

  1. リポジトリのルートで「Create new file」をクリック
  2. ファイル名に「.github/workflows/ci.yml」と入力
  3. GitHub が自動的にディレクトリを作成

2. ローカル環境で作成

# ターミナルでリポジトリルートに移動
mkdir -p .github/workflows
touch .github/workflows/ci.yml

YAMLの基本構文

ワークフローファイルはYAML形式で記述します。YAMLの基本的なルールを理解しておきましょう。

YAML構文の重要ポイント

インデント（字下げ）

# 正しい例
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

# 間違った例（インデントが不統一）
jobs:
  test:
runs-on: ubuntu-latest
  steps:
- name: Checkout

リスト表記

# ハイフン（-）を使用
steps:
  - name: Step 1
  - name: Step 2
  - name: Step 3

# または角括弧
branches: [main, develop, feature/*]

文字列の扱い

# クォートなし（シンプルな文字列）
name: CI Pipeline

# シングルクォート（特殊文字含む）
name: 'CI Pipeline: Build & Test'

# ダブルクォート（変数展開あり）
name: "Build for ${{ github.ref_name }}"

基本的なワークフローファイルの構造

すべてのワークフローファイルは、以下の基本構造を持ちます。

name: ワークフロー名

on: トリガー条件

jobs:
  ジョブ名:
    runs-on: 実行環境
    steps:
      - name: ステップ名
        実行内容

最小限のワークフローファイル例

name: Hello World

on:
  push:
    branches: [main]

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Say Hello
        run: echo "Hello, World!"

実践：初回ワークフローファイル作成

実際に、Node.jsプロジェクト用の基本的なCI ワークフローを作成してみましょう。

ステップ1：ファイル作成

.github/workflows/ci.yml ファイルを作成します。

ステップ2：基本構造を記述

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Run linting
        run: npm run lint

ステップ3：各セクションの解説

name セクション

name: CI

ワークフローの表示名を定義します。GitHub の Actions タブで表示される名前です。

on セクション

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

ワークフローを実行するトリガーを定義します。この例では：

  • main または develop ブランチへのプッシュ時
  • main ブランチへのプルリクエスト作成時

jobs セクション

jobs:
  test:
    runs-on: ubuntu-latest

実行するジョブを定義します。test は任意のジョブ名で、ubuntu-latest は実行環境を指定します。

steps セクション

各ステップで実行する具体的な処理を定義します。

よく使用されるトリガーパターン

基本的なトリガー

# プッシュ時のみ
on: push

# プルリクエスト時のみ  
on: pull_request

# 複数トリガー
on: [push, pull_request]

# 詳細設定
on:
  push:
    branches: [main, 'release/*']
    paths: ['src/**', 'package.json']
  pull_request:
    types: [opened, synchronize, reopened]

スケジュール実行

# 毎日午前2時に実行
on:
  schedule:
    - cron: '0 2 * * *'

# 毎週月曜日の午前10時に実行
on:
  schedule:
    - cron: '0 10 * * 1'

手動実行

# GitHub UIから手動実行可能
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

実行環境の選択

GitHub Actions では、以下の実行環境が利用可能です。

利用可能なランナー

# Ubuntu（最新版）
runs-on: ubuntu-latest

# Ubuntu（特定バージョン）
runs-on: ubuntu-22.04

# Windows
runs-on: windows-latest

# macOS
runs-on: macos-latest

# 複数環境でのテスト
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
runs-on: ${{ matrix.os }}

よくある間違いと対処法

1. インデントエラー

問題：YAMLのインデントが不正

# 間違い
jobs:
test:  # インデントが足りない
  runs-on: ubuntu-latest

解決：一貫した2スペースインデントを使用

# 正しい
jobs:
  test:  # 2スペースのインデント
    runs-on: ubuntu-latest

2. 構文エラー

問題：YAML構文が間違っている

# 間違い
on:
  push
    branches: [main]  # ハイフンが不足

解決：正しいYAML構文を使用

# 正しい
on:
  push:
    branches: [main]

3. ファイルパスエラー

問題：ワークフローファイルが正しい場所にない

解決：必ず .github/workflows/ ディレクトリ内に配置

ワークフローの動作確認

実行結果の確認方法

  1. GitHubリポジトリの「Actions」タブをクリック
  2. 実行されたワークフローを選択
  3. 各ジョブとステップの実行状況を確認
  4. ログの詳細を確認してエラーがないかチェック

デバッグのコツ

# デバッグ用のログ出力
- name: Debug information
  run: |
    echo "Current directory: $(pwd)"
    echo "Files in directory:"
    ls -la
    echo "Environment variables:"
    env | grep GITHUB_

次のステップ

基本的なワークフローファイルが作成できたら、以下を試してみましょう：

  • 複数ジョブの並列実行：テストとリンターを並列で実行
  • 条件付き実行：特定の条件下でのみジョブを実行
  • 環境変数の利用：設定値の外部化
  • アーティファクトの保存：ビルド結果の保存

まとめ

GitHub Actionsのワークフローファイル作成は、以下のポイントを押さえれば決して難しくありません：

  • 正しいディレクトリ構造：.github/workflows/ に配置
  • YAML構文の理解：インデントと構文に注意
  • 基本構造の把握：name、on、jobs、stepsの関係
  • 段階的な作成：シンプルなものから始めて徐々に拡張

まずは簡単なワークフローから始めて、プロジェクトの要件に合わせて徐々に機能を追加していくことをお勧めします。次回は、より高度なワークフロー機能について詳しく解説していきます。

スポンサーリンク
タイトルとURLをコピーしました