GitHub Actions: Workflow run failed の原因と解決策

概要

GitHub Actionsでワークフローの実行が失敗した場合に発生するエラーです。様々な原因があり、ログを確認して特定が必要です。

エラーメッセージ

Error: Process completed with exit code 1.

または

##[error]The process '/usr/bin/docker' failed with exit code 1

原因

テスト失敗: 単体テストやE2Eテストの失敗
ビルドエラー: コンパイルやトランスパイルの失敗
権限不足: トークンやシークレットの設定ミス
環境問題: ランナー環境の問題

解決策

1. ログを確認

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# ログの詳細度を上げる
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Run with debug
        run: |
          set -x  # コマンドを表示
          npm test          
        env:
          ACTIONS_STEP_DEBUG: true

2. テスト失敗時の対処

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        run: npm test
        continue-on-error: true  # 失敗しても続行

      - name: Upload test results
        if: failure()  # 失敗時のみ実行
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: test-results/

3. シークレットの確認

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check secrets
        run: |
          if [ -z "${{ secrets.AWS_ACCESS_KEY_ID }}" ]; then
            echo "AWS_ACCESS_KEY_ID is not set"
            exit 1
          fi          

      - name: Deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: aws s3 sync ./dist s3://my-bucket

4. 依存関係のキャッシュ

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci  # npm install より高速で確実

5. タイムアウトの設定

1
2
3
4
5
6
7
8
jobs:
  long-running:
    runs-on: ubuntu-latest
    timeout-minutes: 30  # デフォルトは360分
    steps:
      - name: Long task
        timeout-minutes: 10  # ステップごとの制限
        run: npm run build

6. マトリックス戦略でのエラー処理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false  # 1つ失敗しても他は続行
      matrix:
        node-version: [16, 18, 20]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

7. 条件付き実行

1
2
3
4
5
6
7
jobs:
  deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'  # mainブランチのみ
    steps:
      - name: Deploy
        run: ./deploy.sh

8. ワークフローのリランとデバッグ

1
2
3
4
5
6
7
8
# GitHub CLIでワークフローを再実行
gh run rerun <run-id>

# 失敗したジョブのみ再実行
gh run rerun <run-id> --failed

# ログを表示
gh run view <run-id> --log-failed

9. 自己ホストランナーの問題

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
jobs:
  build:
    runs-on: self-hosted
    steps:
      - name: Check runner
        run: |
          echo "Runner OS: ${{ runner.os }}"
          echo "Runner arch: ${{ runner.arch }}"
          df -h  # ディスク容量確認
          free -m  # メモリ確認          

10. 環境変数とコンテキスト

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - name: Dump contexts
        run: |
          echo "github.event_name: ${{ github.event_name }}"
          echo "github.ref: ${{ github.ref }}"
          echo "github.sha: ${{ github.sha }}"          
        env:
          GITHUB_CONTEXT: ${{ toJSON(github) }}

よくある間違い

シークレット名のタイポ（大文字小文字に注意）
package-lock.jsonがコミットされていない
actions/checkout を忘れている
ブランチ名の指定ミス（main vs master）