GitHub Actionsで自動テストが実行されない時の原因と解決方法

GitHub Actionsで自動テストが動かない主な原因

GitHub Actionsを設定したのに自動テストが実行されない場合、いくつかの典型的な原因があります。私も最初は「なぜ動かないの？」と頭を抱えることが多かったです。

主な原因は以下の5つです：

1. YAMLファイルの構文エラー - インデントやキーの記述ミス
2. ブランチ名やイベントの不一致 - トリガー条件が満たされていない
3. 権限不足 - リポジトリやトークンの権限設定の問題
4. ワークフローの無効化 - 手動で無効化されているケース
5. リソースの制限 - 無料枠の制限に達している場合

これらの原因を一つずつ確認していくことで、ほとんどの問題は解決できます。

YAMLファイルの記述ミスをチェックする

YAMLファイルは非常にデリケートで、わずかなミスでも動作しません。特に注意すべき点を見ていきます。

インデントの確認

YAMLはインデントに厳密です。スペース2個または4個で統一する必要があります：

# 正しい例
name: Run Tests
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# 間違った例（インデントが不揃い）
name: Run Tests
on:
 push:  # スペース1個しかない
   branches: [ main ]

必須フィールドの確認

最低限必要な要素が揃っているか確認します：

name: CI  # ワークフロー名
on: [push]  # トリガーイベント
jobs:  # ジョブの定義
  test:
    runs-on: ubuntu-latest  # 実行環境
    steps:  # ステップの定義
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test

YAML検証ツールの活用

オンラインのYAML検証ツールやVSCodeの拡張機能を使って、構文エラーを事前にチェックできます。

トリガー条件の設定を確認する

ワークフローが実行されない最も多い原因の一つが、トリガー条件の設定ミスです。

ブランチ名の確認

プッシュやプルリクエストのブランチ名が正しいか確認します：

on:
  push:
    branches: 
      - main  # mainブランチへのプッシュのみ
      - develop
  pull_request:
    branches: [ main ]  # mainブランチへのPRのみ

よくある間違い：

• masterとmainの間違い
• ブランチ名のタイポ
• ワイルドカードの使い方の誤り

パスフィルターの設定

特定のファイルが変更された時のみ実行する設定：

on:
  push:
    paths:
      - 'src/**'  # srcディレクトリ内の変更時のみ
      - '*.js'    # JavaScriptファイルの変更時のみ
    paths-ignore:
      - 'docs/**'  # docsディレクトリは無視

手動実行の設定

手動でワークフローを実行できるようにする：

on:
  workflow_dispatch:  # 手動実行を有効化
  push:
    branches: [ main ]

権限とシークレットの設定を見直す

権限不足はワークフローが失敗する隠れた原因になりがちです。

GITHUB_TOKENの権限設定

デフォルトのGITHUB_TOKENに必要な権限を付与：

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read  # リポジトリの読み取り
      issues: write   # Issue作成権限
      pull-requests: write  # PR操作権限

シークレットの設定確認

外部サービスとの連携に必要なシークレット：

steps:
  - name: Deploy to server
    env:
      API_KEY: ${{ secrets.API_KEY }}  # リポジトリシークレット
      TOKEN: ${{ secrets.GITHUB_TOKEN }}  # 自動生成トークン
    run: |
      echo "Deploying with API key..."

シークレットの設定場所：

1. リポジトリの Settings → Secrets and variables → Actions
2. 名前は大文字とアンダースコアを使用
3. Organization secretsも確認

ワークフローの有効化

新しいフォークやリポジトリでは、ワークフローが無効になっている場合があります：

1. Actions タブを開く
2. 「I understand my workflows, go ahead and enable them」をクリック

ワークフローのデバッグ方法

問題の原因を特定するためのデバッグテクニックを紹介します。

デバッグログの有効化

環境変数でデバッグモードを有効にする：

env:
  ACTIONS_RUNNER_DEBUG: true
  ACTIONS_STEP_DEBUG: true

または、リポジトリのシークレットに設定：

• ACTIONS_RUNNER_DEBUG = true
• ACTIONS_STEP_DEBUG = true

実行状況の確認方法

steps:
  - name: Debug情報の出力
    run: |
      echo "現在のブランチ: ${{ github.ref }}"
      echo "イベント名: ${{ github.event_name }}"
      echo "実行者: ${{ github.actor }}"
      echo "リポジトリ: ${{ github.repository }}"
  
  - name: 環境変数の確認
    run: env | sort
  
  - name: ファイル構造の確認
    run: ls -la

ローカルでのテスト

actを使ってローカルで実行：

# actのインストール
brew install act  # macOS
# または
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# ワークフローの実行
act push  # pushイベントをシミュレート

よくあるエラーメッセージと対処法

実際に遭遇しやすいエラーメッセージとその解決方法をまとめました。

「No workflow file found」

Error: .github#L1
no workflow file was found.

対処法：

• ワークフローファイルが.github/workflows/ディレクトリにあるか確認
• ファイル拡張子が.ymlまたは.yamlか確認
• ファイル名に特殊文字が含まれていないか確認

「Invalid workflow file」

Invalid workflow file
The workflow is not valid. .github/workflows/main.yml#L10

対処法：

# YAMLの検証
yamllint .github/workflows/main.yml

# GitHub CLIで検証
gh workflow view main.yml

「Resource not accessible by integration」

対処法：

permissions:
  contents: write  # 書き込み権限を追加
  pull-requests: write

まとめ

GitHub Actionsが動かない時は、焦らず一つずつ確認していくことが大切です。この記事で紹介した方法を試せば、ほとんどの問題は解決できるはずです。それでも解決しない場合は、GitHub Communityフォーラムで質問してみるのも良いでしょう。