github-actions-validator

GitHub Actions バリデーター

概要

業界標準ツール（actionlint および act）を使用して、GitHub Actions ワークフロー、カスタムアクション、パブリックアクションを検証およびテストします。このスキルでは、構文チェック、静的解析、ワークフローのローカル実行テスト、バージョンに応じたドキュメントの確認を含む、包括的な検証を行います。

トリガーフレーズ

次のようなフレーズを含むリクエストでは、このスキルを使用します。

• 「この GitHub Actions ワークフローを検証して」
• 「.github/workflows/*.yml ファイルを確認して」
• 「actionlint のエラーをデバッグして」
• 「act でこのワークフローをローカルでテストして」
• 「GitHub Action のバージョンや非推奨化を確認して」

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• ワークフローファイルの検証：.github/workflows/*.yml の構文エラーやベストプラクティスを確認する場合
• ワークフローのローカルテスト：GitHub にプッシュする前に、act でワークフローを実行する場合
• ワークフローの失敗のデバッグ：ワークフロー設定の問題を特定する場合
• カスタムアクションの検証：コンポジット、Docker、または JavaScript アクションを確認する場合
• パブリックアクションの検証：GitHub Marketplace のアクションの使用を検証する場合
• コミット前の検証：コミット前にワークフローが有効であることを確認する場合

必須の実行フロー

検証を実行する際は、毎回次の手順を順番に行ってください。

ステップ 1：スキルのパスを設定して検証を実行する

.github/workflows/ を含むリポジトリのルートからコマンドを実行してください。

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>

ステップ 2：各エラーを参照資料に対応付ける

actionlint/act の各エラーについて、以下の対応表を確認し、一致する修正パターンを抽出してください。

ステップ 3：引用を最小限にする方針を適用する

各問題について：

1. ツールの出力からエラー行を正確に記載します。
2. references/ から、必要最小限の有用な抜粋のみを引用します（8 行以下を推奨）。
3. それ以外は言い換え、出典ファイルとセクションを明記します。
4. 修正後のワークフローコードを示します。

ステップ 4：対応表にないエラーを明示的に処理する

対応表に一致するエラーがない場合：

1. UNMAPPED とラベル付けします。
2. ツールの出力、ワークフローファイル、行番号（取得できる場合）を正確に記録します。
3. まず references/common_errors.md の一般的なセクションを確認します。
4. それでも解決しない場合は、正確なエラー文字列で公式ドキュメントを検索します。
5. 修正後の再実行に合格するまでは、修正を provisional としてマークします。

ステップ 5：パブリックアクションのバージョンを確認する

各 uses: owner/action@version について：

1. references/action_versions.md を確認します。
2. 未知のアクションについては、公式ドキュメントで検証します。
3. 必須入力と非推奨化を確認します。

オフラインモードでの動作：

• ネットワークまたはドキュメントの検索が利用できない場合は、references/action_versions.md のみを参照します。
• 未知のアクションは UNVERIFIED-OFFLINE としてマークします。
• オンラインでの検証を行わずに、「最新」バージョンだと断言しないでください。

ステップ 6：修正後に必ず再実行する

修正を適用した後、最終確定の前に検証を再実行してください。

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>

ステップ 7：最終的な概要を提示する

最終出力には次の内容を含めてください。

• 見つかった問題と適用した修正
• UNMAPPED または UNVERIFIED-OFFLINE の項目
• 修正後に再実行したコマンドと結果
• 残っている警告やリスクに関する注記

エラーの種類と参照ファイルの対応表

出力内のエラーパターン	読み込む参照ファイル	引用するセクション
runs-on:, runner, ubuntu, macos, windows	references/runners.md	Runner labels
cron, schedule	references/common_errors.md	Schedule Errors
${{, expression, if:	references/common_errors.md	Expression Errors
needs:, job, dependency	references/common_errors.md	Job Configuration Errors
uses:, action, input	references/common_errors.md	Action Errors
untrusted, injection, security	references/common_errors.md	Script Injection section
syntax, yaml, unexpected	references/common_errors.md	Syntax Errors
docker, container	references/act_usage.md	Troubleshooting
@v3, @v4, deprecated, outdated	references/action_versions.md	Version table
workflow_call, reusable, oidc	references/modern_features.md	Relevant section
glob, path, paths:, pattern	references/common_errors.md	Path Filter Errors

例：エラー対応の完全なワークフロー

ユーザーのワークフローに次のエラーが発生しています：

runs-on: ubuntu-lastest

ステップ 1 - スクリプトの出力：

label "ubuntu-lastest" is unknown

ステップ 2 - references/runners.md または references/common_errors.md を読み込みます： 「Invalid Runner Label」セクションを見つけます。

ステップ 3 - 修正方法をユーザーに引用します：

エラー： label "ubuntu-lastest" is unknown

原因： ランナーラベルのタイプミスです（references/common_errors.md より）：

# Bad
runs-on: ubuntu-lastest  # Typo

修正方法（references/common_errors.md より）：

# Good
runs-on: ubuntu-latest

有効なランナーラベル（references/runners.md より）：

• ubuntu-latest、ubuntu-24.04、ubuntu-22.04
• windows-latest、windows-2025、windows-2022
• macos-latest、macos-15、macos-14

ステップ 4 - 修正済みコードを提示します：

runs-on: ubuntu-latest

クイックスタート

シェルセッションごとに一度設定します：

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"

初期設定

bash "$SKILL_DIR/scripts/install_tools.sh"

これにより、act（ワークフローのローカル実行）と actionlint（静的解析）が scripts/.tools/ にインストールされます。

基本的な検証

# Validate a single workflow
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

# Validate all workflows
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/

# Lint-only (fastest)
bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/ci.yml

# Test-only with act (requires Docker)
bash "$SKILL_DIR/scripts/validate_workflow.sh" --test-only .github/workflows/

検証の基本的なワークフロー

1. actionlint による静的解析

まず静的解析を実行し、構文エラーや一般的な問題を検出します：

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/ci.yml

actionlint のチェック項目： YAML 構文、スキーマへの準拠、式の構文、ランナーラベル、アクションの入力／出力、ジョブの依存関係、CRON 構文、glob パターン、シェルスクリプト、セキュリティ上の脆弱性。

2. act によるローカルテスト

静的解析に合格したら、ワークフローの実行をテストします：

bash "$SKILL_DIR/scripts/validate_workflow.sh" --test-only .github/workflows/

注： act には制限があります。references/act_usage.md を参照してください。

3. 完全な検証

bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

ツールまたはランタイムが利用できない場合のデフォルトの動作：

• act がない場合、完全な検証は actionlint のみの検証にフォールバックします。
• Docker が利用できない場合、完全な検証では act をスキップし、actionlint を続行します。
• --check-versions は、references/action_versions.md を使ってオフライン／ローカルモードで動作します。

リソースの種類ごとの検証

ワークフロー

# Single workflow
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

# All workflows
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/

主な検証ポイント： トリガー、ジョブ設定、ランナーラベル、環境変数、シークレット、条件式、マトリックス戦略。

カスタムローカルアクション

カスタムアクションを使用するテスト用ワークフローを作成し、検証します：

bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/test-custom-action.yml

パブリックアクション

ワークフローでパブリックアクション（例：actions/checkout@v6）を使用する場合：

1. 最初に references/action_versions.md を確認します
2. 不明なアクションについては、公式ドキュメント（またはウェブ検索）を使用します
3. 必須の入力とバージョンを確認します
4. 非推奨の警告がないか確認します
5. 検証スクリプトを実行します

オフラインの場合：

• 不明なバージョンには UNVERIFIED-OFFLINE と記載します
• オンラインで確認できるまでは、「最新／現在」という主張を避けます

検索形式： "[action-name] [version] github action documentation"

参照ファイルの確認ガイド

必須のリファレンス参照

状況	リファレンスファイル	対応
actionlint がマッピング済みのエラーを報告した場合	references/common_errors.md	該当するエラーを確認し、最小限の引用方針を適用します
actionlint がマッピングされていないエラーを報告した場合	references/common_errors.md + 公式ドキュメント	UNMAPPED としてラベル付けし、正確な出力を記録して再実行で検証します
act が Docker／ランタイムエラーで失敗した場合	references/act_usage.md	トラブルシューティングのセクションを確認します
act は失敗するが、GitHub ではワークフローが動作する場合	references/act_usage.md	制限事項のセクションを読みます
ユーザーが actionlint の設定について質問した場合	references/actionlint_usage.md	例を提示します
ユーザーが act のオプションについて質問した場合	references/act_usage.md	詳細オプションを読みます
セキュリティの脆弱性が検出された場合	references/common_errors.md	安全な修正方法の最小限のスニペットを引用します
アクションのバージョンを検証する場合	references/action_versions.md	バージョン表とオフラインに関する注記を確認します
最新機能を使用する場合	references/modern_features.md	構文の例を確認します
ランナーに関する質問／エラーの場合	references/runners.md	ラベルと利用可能状況を確認します

スクリプト出力と参照先の対応

出力パターン	リファレンスファイル
[syntax-check]、解析、YAML エラー	common_errors.md - 構文エラー
[expression]、${{、条件式の解析	common_errors.md - 式のエラー
[action]、uses:、入力／出力の不一致	common_errors.md - アクションのエラー
CRON／schedule の文言を含む [events]	common_errors.md - スケジュールのエラー
potentially untrusted、インジェクションに関する警告	common_errors.md - セキュリティのセクション
[runner-label] または不明な runs-on ラベル	runners.md
[job-needs] の依存関係エラー	common_errors.md - ジョブ設定のエラー
[glob]、paths、パターンのエラー	common_errors.md - パスフィルターのエラー
act の Docker／pull／image エラー	act_usage.md - トラブルシューティング
パターンに一致しない場合	common_errors.md + 公式ドキュメント（UNMAPPED としてラベル付け）

リファレンスファイルの概要

ファイル	内容
references/act_usage.md	Act ツールの使い方、コマンド、オプション、制限事項、トラブルシューティング
references/actionlint_usage.md	Actionlint の検証カテゴリ、設定、統合
references/common_errors.md	修正方法を含む一般的なエラーの一覧
references/action_versions.md	現行のアクションバージョン、非推奨化のスケジュール、SHA ピン留め
references/modern_features.md	再利用可能なワークフロー、SBOM、OIDC、環境、コンテナ
references/runners.md	GitHub ホストランナー（ARM64、GPU、M2 Pro、非推奨化）

トラブルシューティング

問題	解決方法
"Tools not found"	bash "$SKILL_DIR/scripts/install_tools.sh" を実行します
"Docker daemon not running"	Docker を起動するか、--lint-only を使用します
"Permission denied"	chmod +x "$SKILL_DIR"/scripts/*.sh を実行します
act は失敗するが、GitHub では動作する	references/act_usage.md の制限事項を参照してください

デバッグモード

actionlint -verbose .github/workflows/ci.yml  # Verbose actionlint
act -v                                         # Verbose act
act -n                                         # Dry-run (no execution)

ベストプラクティス

1. まず必ずローカルで検証する - プッシュ前にエラーを見つけます
2. CI/CD で actionlint を使用する - パイプラインで検証を自動化します
3. アクションのバージョンを固定する - 安定性のために @main ではなく @v6 を使用し、セキュリティのために SHA をピン留めします
4. ツールを最新の状態に保つ - actionlint と act を定期的に更新します
5. 不明なアクションには公式ドキュメントを使用する - 使い方とバージョンを確認します
6. バージョンの互換性を確認する - references/action_versions.md を参照してください
7. shellcheck を有効にする - シェルスクリプトの問題を早期に検出します
8. セキュリティ警告を確認する - スクリプトインジェクションの問題に対処します

制限事項

• act の制限：GitHub Actions の機能はすべてローカルで動作するわけではありません
• Docker の要件：act を実行するには Docker が起動している必要があります
• ネットワークアクション：一部の GitHub API アクションはローカルで失敗する場合があります
• プライベートアクション：アクセス権がない場合は検証できません
• 実行時の動作：静的解析ですべての問題を検出できるわけではありません
• ファイルの場所：act が検証できるのは .github/workflows/ ディレクトリ内のワークフローのみです。examples/ などのディレクトリにあるファイルは actionlint でのみ検証できます

簡単な例

例 1：コミット前の検証

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/
git add .github/workflows/ && git commit -m "Update workflows"

例 2：失敗するワークフローのデバッグ

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/failing.yml
# Fix issues
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/failing.yml

完全な実例：複数のエラーがあるワークフロー

この例では、複数のエラーに対処するためのアシスタントのワークフロー全体を示します。

ユーザーの問題のあるワークフロー

name: Broken CI
on:
  schedule:
    - cron: '0 0 * * 8'  # ERROR 1
jobs:
  build:
    runs-on: ubuntu-lastest  # ERROR 2
    steps:
      - uses: actions/checkout@v3  # ERROR 3 (outdated)
      - run: echo ${{ github.event.issue.title }}  # ERROR 4 (security)
  deploy:
    needs: biuld  # ERROR 5 (typo)
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

ステップ 1：検証を実行する

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only workflow.yml

出力：

[ERROR] invalid CRON format "0 0 * * 8"
[ERROR] label "ubuntu-lastest" is unknown
[WARN] "github.event.issue.title" is potentially untrusted
[ERROR] job "deploy" needs job "biuld" which does not exist

ステップ 2～3：リファレンスを参照し、修正方法を提示する

---

エラー 1：無効な CRON 式

references/common_errors.md の「スケジュールエラー」より：

原因： 曜日 8 は存在しません（有効な値：0～6、0 = 日曜日）

# 誤り
schedule:
  - cron: '0 0 * * 8'  # 8 曜日は存在しません

# 正しい例
schedule:
  - cron: '0 0 * * 0'  # 日曜日

CRON の形式： minute hour day month weekday

• 曜日：0～6（0 = 日曜日）

修正： 8 を 0（日曜日）または 1-6（月曜日～土曜日）に変更します。

---

エラー 2：無効なランナーラベル

references/common_errors.md の「ジョブ設定エラー」および references/runners.md より：

原因： ランナーラベルの入力ミス

# 誤り
runs-on: ubuntu-lastest  # 入力ミス

# 正しい例
runs-on: ubuntu-latest

有効なラベル（references/runners.md より）：

• ubuntu-latest（Ubuntu 24.04）
• ubuntu-24.04、ubuntu-22.04
• macos-latest（macOS 15）
• windows-latest（Windows Server 2022）

修正： ubuntu-lastest を ubuntu-latest に変更します。

---

エラー 3：古いアクションのバージョン

references/action_versions.md より：

アクション	最新バージョン	サポートされる最小バージョン
actions/checkout	v6	v4

SHA ピン留めのベストプラクティス：

# 推奨：バージョンのコメントを付けて SHA でピン留めする
- uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0

修正： @v3 を @v6（または SHA でピン留めしたバージョン）に更新します。

---

エラー 4：セキュリティの脆弱性（スクリプトインジェクション）

references/common_errors.md の「式のエラー」より：

警告： 信頼できない入力を介したスクリプトインジェクションの可能性があります

# 悪い例：インジェクションに対して脆弱です
run: echo ${{ github.event.issue.title }}

# 良い例：環境変数を使用します
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"

理由： 信頼できない入力（イシューのタイトル、PR の本文、コミットメッセージ）には、悪意のあるコマンドが含まれる可能性があります。環境変数を使用すると、入力がサニタイズされます。

修正： 信頼できない入力を環境変数経由で渡します。

---

エラー 5：未定義のジョブ依存関係

references/common_errors.md の「ジョブ設定エラー」より：

エラー： ジョブ 'deploy' は、存在しないジョブ 'biuld' に依存しています

# 誤り
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: biuld  # 入力ミス

# 正しい例
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: build

修正： biuld を build に変更します。

---

ステップ 4：修正済みのワークフローを提示する

name: Fixed CI
on:
  schedule:
    - cron: '0 0 * * 0'  # Fixed: Sunday (0-6 valid)
jobs:
  build:
    runs-on: ubuntu-latest  # Fixed: typo corrected
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0 - Fixed: updated version
      - name: Process issue
        env:
          TITLE: ${{ github.event.issue.title }}  # Fixed: use env var
        run: echo "$TITLE"
  deploy:
    needs: build  # Fixed: typo corrected
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

ステップ 5：必ず再実行する

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only workflow.yml

再実行で期待される結果：

• 以前のエラーが再現されない
• 残っている警告があれば、明確に記録されている

ステップ 6：まとめ

エラー	種類	適用した修正
CRON 0 0 * * 8	スケジュール	0 0 * * 0 に変更
ubuntu-lastest	ランナー	ubuntu-latest に変更
checkout@v3	古いアクション	@v6.0.0 に更新（SHA で固定）
run 内の直接的な ${{ }}	セキュリティ	環境変数でラップ
needs: biuld	ジョブの依存関係	needs: build に変更

推奨事項：

• bash "$SKILL_DIR/scripts/validate_workflow.sh" --check-versions を定期的に実行してください
• 本番環境のワークフローでは、すべてのアクションを SHA で固定してください
• 信頼できない入力は、必ず環境変数を通じて渡してください

完了条件

以下の条件をすべて満たしたとき、検証作業は完了です：

• トリガーが一致し、正しい検証モードが選択されている。
• マッピングされた各エラーに、参照元と最小限の引用が含まれている。
• マッピングされていない各エラーに UNMAPPED のラベルが付けられ、出力が正確に記録されている。
• 公開アクションのバージョンが検証済みであるか、UNVERIFIED-OFFLINE とマークされている。
• 修正後に再実行され、結果が報告されている。

まとめ

1. セットアップ：install_tools.sh でツールをインストールします
2. 検証：ワークフローファイルに対して validate_workflow.sh を実行します
3. 修正：リファレンスドキュメントを使って問題に対処します
4. 再実行：必須の修正後検証を実行して、修正を確認します
5. 検索：公式ドキュメントを使って不明なアクションを確認します
6. コミット：検証済みのワークフローを安心してプッシュします

詳細については、references/ 内の該当するリファレンスファイルを参照してください。