mcpField
A
authoring-github-workflows

authoring-github-workflows

github.com/dotnetクラウド・DevOps5.8k3.2k 回インストール1 日前に更新
リポジトリ

authoring-github-workflows について

GitHub Actions のワークフロー YAML を作成・レビューする開発者向けのスキルです。YAML と Actions の構文上の落とし穴、式を含む値の引用符、actionlint による検証を扱います。

主な機能

  1. 01式に含まれる YAML コメントの罠を特定
  2. 02引用符が必要なスカラー値を判別
  3. 03actionlint でワークフローを検証
  4. 04YAML 解析と Actions 検証を区別
  5. 05マージ前の確認項目を提示

活用シーン

  1. 01.github/workflows/ 内のファイルを編集・レビューする
  2. 02ジョブが開始しないワークフローエラーを調査する
  3. 03`${{ }}` 式を含むフィールドを確認する

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/dotnet/skills --skill authoring-github-workflows

インストール後、Claude Code で/authoring-github-workflowsを入力して読み込まれたか確認します。

詳細

GitHub Actions ワークフローを安全に作成する

GitHub Actions のワークフローファイルは YAML ですが、有効な YAML が有効なワークフローとは限りません。yaml.safe_load で問題なく解析できても（あるいは軽くレビューしただけでも）、読み込み時に GitHub Actions に拒否され、ジョブが一つも開始されないまま、原因が分かりにくい 「この実行はワークフローファイルの問題により失敗した可能性があります」 というエラーが発生することがあります。このスキルでは、YAML と Actions の落とし穴（特に上記の # がコメントとして扱われる問題）、式スカラーを正しく引用する方法、マージ前に actionlint で検証する方法を説明します。

対象範囲：構文上の正しさと意味上の正しさ。 このスキルでは、ワークフロー YAML の構文上および構造上の正しさ、つまり GitHub Actions がファイルを読み込んで実行できるかどうかを左右する、引用、解析、actionlint レベルの妥当性を扱います。ワークフローで何を行うべきか、あるいはエージェント型ワークフローがどのように動作すべきかは扱いません。意味上および機能上の指針（ワークフローロジックの設計、エージェント型ワークフローのパターン、gh-aw の作成）については、.github/agents/agentic-workflows.agent.md を使用してください。この 2 つは相互に補完するものです。エージェントを使って動作を正しく設計し、このスキルを使って YAML を正しく記述してください。

使用する場面

  • .github/workflows/ 以下のファイルを編集、追加、レビューするとき。
  • ${{ }} 式を含む run-name、name、if、env、with、または run の値を記述するとき。
  • 「この実行はワークフローファイルの問題により失敗した可能性があります」 というエラーでワークフローの実行に失敗し、ジョブが一つも実行されなかったとき。
  • 変更内容に問題がなさそうに見えたにもかかわらず、ワークフローの変更をマージした後、main 上の Eval/CI がすべての実行で突然失敗するとき。
  • YAML スカラーを引用する必要があるか判断するとき。

使用しない場面

  • Actions 以外の YAML（アプリ設定、Kubernetes、Compose、Azure Pipelines、GitLab CI）を作成するとき。
  • 有効な run: ブロック内のシェル／スクリプトロジックだけを扱うとき（これはワークフロー構文の作業ではなく、スクリプト作成の作業です）。

最大の落とし穴：引用符で囲まれていない式内の # は YAML コメントになる

YAML では、空白の後に # が続くとコメントが始まります。引用符で囲まれていない（プレーンな）スカラーでは、空白と # 以降の行末までの内容がすべて黙って破棄されます。

# BAD — the run-name is silently truncated at " #"
run-name: ${{ inputs.pr_number != '' && format('Evaluate PR #{0} @ {1}', inputs.pr_number, inputs.head_sha) || '' }}

YAML はこれを run-name: ${{ inputs.pr_number != '' && format('Evaluate PR として解析します。これは終了していない ${{ 式です。yaml.safe_load は正常に処理します（末尾にコメントが付いた、途中で切れた文字列として認識するだけです）。そのため、このバグは単純な検証をすり抜けますが、GitHub Actions は不正な式を拒否し、実行を一切開始しません。

# GOOD — wrap the whole value in double quotes so '#' stays inside the scalar
run-name: "${{ inputs.pr_number != '' && format('Evaluate PR #{0} @ {1}', inputs.pr_number, inputs.head_sha) || '' }}"

内部の式ですでにシングルクォートを使っているため、スカラーをダブルクォートで囲んでも安全です。これは、dotnet/skills の main での評価を妨げたものとまったく同じバグです（PR #746 → 引用符で囲んで修正）。

プレーンなスカラーで引用符が必要になるその他の文字

文字／パターン問題が起きる理由対処方法
空白の後に #（空白とシャープ）YAML コメントが始まり、値が途中で切れる値全体を引用符で囲む
先頭の *、&、!、?、|、>、@、`YAML のアンカー／エイリアス／タグ／ブロックスカラーとして解釈される値を引用符で囲む
先頭の { または [フローマッピング／シーケンスとして解析される（単独の ${{ }} は $ で始まるため安全ですが、先頭文字の後に続く {{ は危険です）値を引用符で囲む
値の中の : の後に空白入れ子のマッピングキーとして解析される値を引用符で囲む
意味のある先頭／末尾の空白プレーンスカラーでは削除される値を引用符で囲む
値が true／false／yes／no／on／off／数値だが、文字列として扱う必要がある場合YAML の型変換値を引用符で囲む

目安： name、run-name、if、env、with の値に ${{ }} 式が含まれ、さらにリテラルの #、:、または先頭の特殊文字がある場合は、スカラー全体をダブルクォートで囲んでください。

ワークフロー

ステップ 1：変更した／作成したワークフローファイルを特定する
git diff --name-only origin/main... -- .github/workflows/

各ファイルについて、${{ と #、コロンの後の空白、または先頭の特殊文字を含むすべての行を確認します。

ステップ 2：リスクのある式スカラーを引用符で囲む

値に式が含まれ、かつ # やその他の特殊文字を含む場合は、値全体を二重引用符で囲みます（上の表を参照）。式の内部で単一引用符を使っている場合は二重引用符を、逆の場合は単一引用符を優先してください。${{ }} の波括弧をエスケープしてはいけません。スカラーを引用符で囲めば十分です。

ステップ 3：actionlint で検証する（正式な方法）

actionlint は GitHub Actions のスキーマと式の文法の両方を理解しているため、通常の YAML リンターでは見逃すこの種のバグを正確に検出できます。バージョンを固定してダウンロードし、実行してください。

ACTIONLINT_VERSION=1.7.7
ACTIONLINT_SHA256=023070a287cd8cccd71515fedc843f1985bf96c436b7effaecce67290e7e0757
curl -fsSLo actionlint.tar.gz \
  "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
# Verify the download against the pinned checksum before extracting/executing it:
echo "${ACTIONLINT_SHA256}  actionlint.tar.gz" | sha256sum -c -
tar -xzf actionlint.tar.gz actionlint
# Focus on workflow/expression correctness; silence shell/py style noise:
./actionlint -shellcheck= -pyflakes= -color .github/workflows/*.yml

Windows PowerShell では、actionlint_<ver>_windows_amd64.zip アセットを使用し、Expand-Archive を実行してください。

式が途中で切れるバグは、次のように表示されます。

got unexpected EOF while lexing end of string literal, expecting ''' [expression]

終了コードが 0 であれば、ワークフローの構造は有効です。

ステップ 4：YAML のみのチェックでは不十分であることを確認する

yaml.safe_load、yamllint、または「解析できる」ことを証明として頼りにしてはいけません。これらは式が途中で切れてコメントとして扱われる形式を受け入れます。Actions のレイヤーを検証できるのは、actionlint（または変更をプッシュし、GitHub Actions が解析する様子を確認すること）だけです。

ステップ 5：CI ゲートを通過させる

このリポジトリでは、.github/workflows/ に変更がある PR に対して actionlint が自動実行されます（.github/workflows/actionlint.yml を参照）。レビューを依頼する前に、変更がこのチェックに合格することを確認してください。新しいワークフローを追加した場合も、自動的にゲートの対象になります。

検証

  • #、コロンとスペースの組み合わせ、または先頭に特殊文字を含むすべての ${{ }} の値が、引用符で囲まれている。
  • actionlint -shellcheck= -pyflakes= .github/workflows/*.yml の終了コードが 0 である。
  • どのワークフロー実行にも "This run likely failed because of a workflow file issue" と表示されない。
  • PR の actionlint CI チェックが成功している。

よくある落とし穴

落とし穴解決策
式の内部に # があるのに、run-name／name を引用符で囲まない値全体を二重引用符で囲みます
yaml.safe_load／yamllint／コードレビューで検出できると信頼するactionlint を実行します。YAML のみのチェックでは、式が途中で切れた形式が受け入れられます
${{ の波括弧をエスケープして「修正」しようとするしてはいけません。代わりにスカラーを引用符で囲みます。エスケープすると式が壊れます
単一引用符を含む値を単一引用符で囲む外側のスカラーには二重引用符を使います
shellcheck を有効にして actionlint を追加し、既存のシェルスタイルに関する警告が大量に出る-shellcheck= -pyflakes= を指定して、ワークフロー／式のエラーに絞ります
YAML リンターが成功すればワークフローも実行されると思い込むプッシュしてジョブが実際に開始することを確認するか、actionlint ゲートを利用します

参考資料

コメント

Markdown 対応