GitHub Actionsのworkflowファイルとは?

workflowファイルは、GitHub Actionsで何をいつ実行するかを定義するファイルです。基本的にはリポジトリ内の .github/workflows/ に置かれ、変更すると自動実行や公開処理に影響することがあります。

このページでわかること

  • workflowファイルの場所と役割がわかる
  • name、on、jobs、stepsの考え方をつかむ
  • CodexやAIで修正する前に差分確認する理由がわかる

まず確認すること

  • 対象repoの .github/workflows/ を確認する
  • どのtriggerで動くか見る
  • Secretsやpermissionsを扱っていないか確認する

やってはいけないこと

  • 機密値をyamlへ直接書く
  • 動作確認なしに本番公開へつなげる
  • AIが出したworkflowをそのまま採用する

安全寄りに進める手順

  1. 対象のrepo、branch、PR、Actions runを確認する。
  2. Secrets、APIキー、token、.env、個人情報が差分やログに出ていないか見る。
  3. 必要な場合は値を停止または再発行し、影響範囲を整理する。
  4. 変更は小さなbranchとPRに分け、CIとreviewで確認する。

CodexやAI作業時の注意

AIに作業を渡す時は、対象ファイル、触らないファイル、確認項目を明記します。認証情報や実際のキー値は本文、Issue、PR説明、ログ、レポートに残さないようにします。

公式情報で確認する領域

Actions、Secrets、PR、repository visibility、workflow permissionsは仕様が変わることがあります。実作業前にはGitHub Docsで最新の説明を確認してください。

置き場所・拡張子・主なキー(公式)

  • 置き場所と拡張子: GitHub Docsは、workflowファイルをリポジトリの .github/workflows に置くこと、拡張子は .yml か .yaml であることを求めています。
  • name: Actionsの画面に出る名前です。省略すると、リポジトリの直下からのファイルパスが表示されます。
  • on: workflowを起動するイベントです。push などのイベントに、種類や絞り込みを足せます。
  • jobs: 1回の実行は1つ以上のjobでできていて、既定では並列に動きます。
  • runs-on: 各jobが動くrunnerの環境を指定します。
  • 公式の概要では、workflowはjobを動かす自動処理、jobは同じrunnerで動くstepの集まり、stepはシェルスクリプトかactionで、順に実行されます。1つのrunnerが同時に動かせるjobは1つです。
  • 1つのリポジトリに複数のworkflowを置けます。起動は、リポジトリでのイベント、手動、スケジュールの3つで、REST APIの呼び出しでも起動できます。

出典: Workflow syntax for GitHub Actions、Understanding GitHub Actions/確認日 2026年11月2日

permissionsとconcurrencyの書き方

  • permissions は、自動で渡される GITHUB_TOKEN の既定の権限を変えるキーです。ファイルの先頭に書けば全jobに、jobの中に書けばそのjobだけに効きます。
  • 各権限には read、write、none を指定でき、write は read を含みます。公式は、1つでも権限を指定すると、指定しなかった権限はすべて none になるとしています。
  • まとめて指定する書き方として read-all、write-all、{}(すべて無効)があります。
  • concurrency は、同じグループで同時に動くjobやworkflowを1つに制限します。既定では、新しく待ちになった実行が、同じグループで待っている実行を置き換えます。cancel-in-progress: true を付けると、すでに動いている実行も取り消します。グループ名は大文字小文字を区別しません。

AIにworkflowを直させる時は、差分の中で permissions の行が増えていないかを最初に見ると、権限が広げられていないかを確かめられます。

出典: Workflow syntax for GitHub Actions/確認日 2026年11月2日

関連ページ