GitHub Actionsワークフローが失敗する時の原因と解決法！初心者でも5分で修正できる実践ガイド

GitHub Actionsでよく発生するエラーの種類

GitHub Actionsを使い始めると、様々なエラーに遭遇することがあります。エラーメッセージを見ても原因が分からず、困ってしまうことも多いですよね。ここでは、実際によく発生するエラーを種類別に整理します。

構文エラー（Syntax Error）

# よくあるエラー例
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      - run: echo "Hello World"  # インデントエラー

権限エラー（Permission Error）

Error: Resource not accessible by integration

このエラーは、GitHubトークンの権限不足が原因です。

依存関係エラー（Dependency Error）

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

タイムアウトエラー

Error: The operation was canceled.

ジョブが6時間の制限時間を超えたときに発生します。

環境変数エラー

Error: Input required and not supplied: token

必要な環境変数やシークレットが設定されていない場合に発生します。

ワークフロー構文エラーの見つけ方と修正方法

YAMLの構文エラーは最も頻繁に遭遇する問題です。GitHubは親切にエラー箇所を教えてくれますが、実際の修正方法を見ていきましょう。

エラーの確認方法

1. GitHubリポジトリの「Actions」タブを開く
2. 失敗したワークフローをクリック
3. エラーメッセージで行番号を確認

よくある構文エラーと修正例

インデントエラーの修正：

# 誤り
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      - run: npm install  # スペース2つ不足

# 正しい
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - run: npm install  # 正しいインデント

文字列のクォート忘れ：

# 誤り
- run: echo Hello World ${{ github.event.head_commit.message }}

# 正しい
- run: echo "Hello World ${{ github.event.head_commit.message }}"

YAMLのオンライン検証ツール 構文をチェックするには、YAML Lintなどのツールを使うと便利です。ワークフローをコミットする前に検証することで、エラーを未然に防げます。

権限エラーとトークン設定の解決策

「Resource not accessible by integration」というエラーは、多くの開発者を悩ませる問題です。これは主にGITHUB_TOKENの権限設定に起因します。

基本的な権限設定

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # リリース作成に必要
      pull-requests: write  # PR操作に必要
    steps:
    - uses: actions/checkout@v3
    - name: Create Release
      uses: actions/create-release@v1
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

よくある権限エラーと解決方法

1. Issue/PRへのコメント追加時

permissions:
  issues: write
  pull-requests: write

2. Pagesへのデプロイ時

permissions:
  pages: write
  id-token: write

3. パッケージの公開時

permissions:
  packages: write
  contents: read

Personal Access Token (PAT) の使用 GITHUB_TOKENでは権限が不足する場合、PATを使用します：

- name: Push changes
  env:
    GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
  run: |
    git push origin main

依存関係とキャッシュに関する問題の対処法

Node.jsプロジェクトでよく見る「npm ERR! ERESOLVE」エラーは、パッケージの依存関係の競合が原因です。GitHub Actions環境では、ローカルと異なる動作をすることがあります。

npm依存関係エラーの解決

- name: Install dependencies
  run: |
    npm ci --legacy-peer-deps  # peer dependencyエラーを回避
    # または
    npm install --force  # 競合を無視して強制インストール

キャッシュを使った高速化

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

キャッシュのクリア方法 キャッシュが原因で問題が発生する場合：

# キャッシュキーを変更して新しいキャッシュを作成
key: ${{ runner.os }}-node-v2-${{ hashFiles('**/package-lock.json') }}

Python依存関係の処理

- name: Cache pip packages
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
    
- name: Install dependencies
  run: |
    pip install --upgrade pip
    pip install -r requirements.txt

デバッグモードを使った原因特定のテクニック

エラーメッセージだけでは原因が分からない場合、デバッグモードが役立ちます。ワークフローの実行状況を詳しく確認できます。

ステップデバッグの有効化

- name: Enable step debug logging
  run: echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV

- name: Debug information
  run: |
    echo "Current directory: $(pwd)"
    echo "Files in directory:"
    ls -la
    echo "Environment variables:"
    env | sort

条件付きデバッグ出力

- name: Debug on failure
  if: failure()
  run: |
    echo "Previous step failed. Debugging information:"
    echo "Exit code: $?"
    cat error.log || echo "No error log found"

ランナーのデバッグ情報

- name: Runner context
  env:
    RUNNER_CONTEXT: ${{ toJson(runner) }}
  run: echo "$RUNNER_CONTEXT"

- name: GitHub context  
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
  run: echo "$GITHUB_CONTEXT"

インタラクティブデバッグ（tmate）

- name: Setup tmate session
  if: ${{ failure() }}
  uses: mxschmitt/action-tmate@v3
  timeout-minutes: 15

これにより、SSHでワークフロー環境に接続してデバッグできます。

エラー予防のためのベストプラクティス

エラーを事前に防ぐことが、最も効率的な開発方法です。以下のベストプラクティスを実践することで、ワークフローの安定性が向上します。

ローカルでの事前テスト actを使用してローカルでワークフローをテストできます：

# actのインストール
brew install act  # macOS
# ワークフローの実行
act -j build

タイムアウトの設定

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30  # ジョブのタイムアウト
    steps:
    - uses: actions/checkout@v3
    - name: Long running task
      timeout-minutes: 10  # ステップのタイムアウト
      run: ./build.sh

エラーハンドリングの実装

- name: Safe execution
  run: |
    set -euo pipefail  # エラー時に即座に停止
    npm test || {
      echo "Tests failed. Check logs above."
      exit 1
    }

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

# .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@v3
      with:
        node-version: ${{ inputs.node-version }}

これらのテクニックを組み合わせることで、GitHub Actionsのエラーを効率的に解決し、安定したCI/CDパイプラインを構築できます。エラーに直面しても、この記事で紹介した方法を順番に試してみてください。きっと5分以内に解決策が見つかるはずです！