GitHub Actionsトラブルシューティングスキル

このスキルは、現在のリポジトリのGitHub Actionsワークフローを分析し、トラブルシューティングするのに役立ちます。

このスキルの使用時期

• ユーザーがCI/CD障害またはビルドエラーについて尋ねている
• ユーザーが「GitHub Actions」「ワークフロー」「パイプライン」または「CIログ」に言及している
• ユーザーが最近のワークフロー実行のステータスを確認したい
• ユーザーが失敗したコミットまたはプルリクエストをトラブルシューティングする必要がある
• ユーザーが特定のワークフロー実行について尋ねている

前提条件

gh CLIの利用可能性を確認します：

which gh

gh が利用できない場合は、GitHubクライアント（gh）が必要であることをユーザーに通知し、ユーザーのプラットフォーム用のインストール手順を提供します。

認証とアクセス

開始する前に、gh がリポジトリへのアクセス権を持つ正しいアカウントで認証されていることを確認します：

# 現在の認証ステータスを確認
gh auth status

# アクティブなアカウントを確認
gh api user --jq '.login'

重要：リポジトリが組織に属している場合（例：organization/repo）、認証されたアカウントがその組織へのアクセス権を持つことを確認します。

インタラクティブなアカウント切り替え

check_gh_cli() 関数はリポジトリアクセスを自動的に検証し、インタラクティブなターミナルで実行する場合：

• 現在のアカウントがリポジトリへのアクセス権を持たないことを検出
• 利用可能なすべての認証済みアカウントを一覧表示
• 正しいアカウントを選択して切り替えるよう促す
• 選択したアカウントがアクセス権を持つことを確認
• アクセスが付与された場合、自動的に進行

インタラクティブセッションの例：

Current account 'personal-user' cannot access 'company/private-repo'

Available accounts:
 1. personal-user
 2. work-user

Select an account to switch to (1-2, or 'n' to skip): 2
Switching to account: work-user
Successfully switched to work-user
✓ Account work-user has access to company/private-repo

非インタラクティブな環境（スクリプト、CI/CD）では、関数は代わりに手動で対応するための指示を含むエラーメッセージを表示します。

一般的な認証の問題：

• 間違ったアカウント：個人アカウントで認証されているが、リポジトリは組織にある
• 複数のアカウント：gh auth switch を使用して正しいアカウントに切り替える必要がある
• 権限がない：アカウントがプライベートリポジトリまたは組織へのアクセス権を持たない

ステップ1：GitHubリポジトリの検出

現在のディレクトリがGitHubリポジトリであるかを確認します：

git remote get-url origin 2>/dev/null | grep -q github.com

これが失敗するか、GitHub以外のURLを返した場合、これはGitHubリポジトリではないことをユーザーに通知します。

オーナーとリポジトリ名を抽出します：

git remote get-url origin | sed -E 's#.*github\.com[:/]([^/]+)/([^.]+)(\.git)?#\1/\2#'

ステップ2：GitHub Actionsが有効になっているかを確認

Actionsが設定されているかを確認する2つの方法：

方法1：ワークフローファイルを確認

ls -la .github/workflows/

方法2：GitHub APIをクエリ

gh api repos/:owner/:repo/actions/workflows --jq '.total_count'

ワークフローが存在しない場合、このリポジトリでGitHub Actionsが設定されていないことをユーザーに通知します。

ステップ3：ワークフロー実行の検索

コミットSHAで検索

ユーザーが特定のコミットに言及または参照HEADについて述べている場合：

# 必要に応じてコミットSHAを取得
COMMIT_SHA=$(git rev-parse HEAD)

# そのコミットの実行を検索
gh run list --commit $COMMIT_SHA --json databaseId,status,conclusion,workflowName,headBranch,createdAt --limit 10

ブランチで検索

gh run list --branch <branch-name> --json databaseId,status,conclusion,workflowName,createdAt --limit 10

最近の失敗

gh run list --status failure --json databaseId,status,conclusion,workflowName,headBranch,createdAt --limit 5

すべての最近の実行

gh run list --limit 20 --json databaseId,status,conclusion,workflowName,headBranch,createdAt

ステップ4：ワークフロー実行の詳細表示

サマリービュー

gh run view <run-id> --verbose

これにより以下が表示されます：

• ワークフロー名とステータス
• トリガーされた元とイベント
• すべてのジョブとそのステータス
• --verbose 使用時のジョブステップ

ステータスのみを確認

gh run view <run-id> --json status,conclusion,workflowName,headBranch --jq '.'

ステップ5：ログの分析

失敗したステップのみ（最初に推奨）

gh run view <run-id> --log-failed

失敗したステップのログのみを表示し、問題を特定しやすくします。

完全なログ

gh run view <run-id> --log

特定のジョブログ

# 最初にジョブを一覧表示してジョブIDを取得
gh run view <run-id> --json jobs --jq '.jobs[] | {id: .databaseId, name: .name, status: .status, conclusion: .conclusion}'

# 次に特定のジョブを表示
gh run view <run-id> --job <job-id> --log

ステップ6：一般的なトラブルシューティングパターン

パターン：最近のプッシュが失敗した

# 最後のコミットSHAを取得
COMMIT_SHA=$(git rev-parse HEAD)

# そのコミットの実行を検索
RUNS=$(gh run list --commit $COMMIT_SHA --json databaseId,status,conclusion,workflowName)

# 失敗がある場合は、実行IDを取得して失敗ログを表示
RUN_ID=$(echo "$RUNS" | jq -r 'first(.[] | select(.conclusion == "failure")) | .databaseId')

if [ -n "$RUN_ID" ]; then
  echo "Found failed run: $RUN_ID"
  gh run view $RUN_ID --log-failed
fi

パターン：マージ前のCIステータスを確認

# 現在のブランチを取得
BRANCH=$(git branch --show-current)

# このブランチの最近の実行を表示
gh run list --branch $BRANCH --limit 5 --json databaseId,status,conclusion,workflowName,createdAt

パターン：成功した実行と比較

# ワークフローの最後の成功した実行を検索
gh run list --workflow <workflow-name> --status success --limit 1 --json databaseId,headSha

# 失敗した実行を検索
gh run list --workflow <workflow-name> --status failure --limit 5 --json databaseId,headSha,createdAt

ヘルパースクリプト

一般的な操作については、scripts/gh_actions_helper.sh のヘルパースクリプトを使用します：

source "$(dirname "$0")/scripts/gh_actions_helper.sh"

# GitHubリポジトリでActionsが有効であることを確認
check_github_actions_repo

# 現在のコミットの最新実行を取得
get_latest_run_for_commit "$(git rev-parse HEAD)"

# ログの一般的な障害パターンを分析
analyze_failure_logs "$RUN_ID"

エラー処理

gh が認証されていない

gh auth status

認証されていない場合：

gh auth login

間違ったアカウントまたは不十分なアクセス権

組織リポジトリへのアクセス時に HTTP 404: Not Found などのエラーが表示される場合：

# 現在アクティブなアカウントを確認
gh auth status
gh api user --jq '.login'

# すべての認証済みアカウントを一覧表示
gh auth status --show-token=false

# 別のアカウントに切り替え
gh auth switch

# または正しいアカウントでログイン
gh auth login

check_gh_cli() ヘルパー関数はこれを自動的に検出し、使用しているアカウントと必要なものについて具体的なガイダンスを提供します。

レート制限

GitHub APIにはレート制限があります。ステータスを確認します：

gh api rate_limit

プライベートリポジトリ

gh が適切な権限を持つことを確認します：

gh auth refresh -s read:org,repo

ユーザーへの出力

常に以下を提供します：

1. コンテキスト：失敗したワークフロー/ジョブが何か
2. ステータス：現在の状態（失敗、進行中など）
3. 主要なエラー：ログから関連するエラーメッセージを抽出
4. 実行可能な次のステップ：何を修正または調査するか

レスポンス形式の例：

Workflow "CI" failed on commit abc123 (5 minutes ago)

Failed job: "test"
Failed step: "Run tests"

Error found:
  ERROR: Test suite failed
  FAILED tests/test_api.py::test_endpoint - AssertionError

Next steps:
- Run `pytest tests/test_api.py::test_endpoint` locally
- Check recent changes to test_api.py or endpoint logic