INFRASTRUCTURE LEARNINGインフラ学習
インフラ大全インフラ大全IT INFRASTRUCTURE / LEARNING
インフラ学習ガイド
教材・演習を探す/

Escで閉じる · 検索語は送信しません

LEARNINGEN

GITHUB · 入門

GitHub Actions入門:workflow・job・step・runnerと権限

GitHub Actionsは、イベントなどをきっかけに定義済みの処理を実行する仕組みです。PRのSQL変更を検査する例で、何が起動し、どこで動き、どの権限を使うかを整理します。検査の成功と、レビュー・マージ・配信は分けて考えます。

この教材で学ぶこと

event・workflow・job・step・runnerの構造と、非信頼コードへ権限を渡さない境界を説明できる。

先に知っておくこと

PRは変更の取り込み提案、checksは特定の対象への検査結果です。YAMLは設定を記述する形式。このページでは実際のworkflowやrunnerを作りません。

何がきっかけで、どこで動く?

PRの検査を考えるための構造
EVENT
PRが更新される

起動のきっかけ。どのイベントに反応するかを定義する。

WORKFLOW
処理の全体定義

YAMLに、起動条件と一つ以上のjobを定義する。

JOB / RUNNER
runnerでjobを実行

runnerは実行環境。jobはそこで動く処理のまとまり。

STEPS
job内の手順

対象revisionを読む、条件を検査する、報告する、など。

矢印のない区画で起動と実行の構造を分けています。これは実行ログではありません。複数jobは依存関係によって並行にも直列にもなります。

eventは起動のきっかけ、workflowは全体定義、jobは処理のまとまり、stepはその中の手順、runnerは実行環境です。workflowは通常.github/workflows内のYAMLで定義します。PRだけでなく、手動起動やスケジュール等もあります。表示されたコードやPRタイトルも、runnerへ届けば入力になります。

jobをファイルの上から書いた順へ、必ず直列に実行するわけではありません。job間の前提はneedsなどで定義し、依存しないjobは並行に動けます。同じjob内のstepの順序と区別します。条件式や失敗・スキップの扱いも、実行結果を読むときの確認項目です。

検査が読んだrevisionを確認する

架空PR #42は、承認済みレポートの抽出へregion = JPを加える提案Hです。開いたマージ可能PRの通常のpull_requestイベントでは、既定のrefはマージ検査用の対象を指します。ここではTと呼びます。HとTは別であり、workflowの起動だけでは何をcheckoutしたかまで断定できません。

読む値を混ぜない
値何を表すか
GITHUB_REFイベントに対応するref。通常の開いたPRでは検査用merge ref。
GITHUB_SHAそのイベントのrefに対応するコミット。
github.event.pull_request.head.sha提案ブランチの先端。既定の検査用merge commitとは区別。

検査内容も固定します。3行の例はR-A = approved / JP、R-B = approved / US、R-C = pending / JP。新しいAND条件なら予想結果はR-Aだけです。ただし、この例の評価が合っても実DBの照合順序・NULL・データ量・業務要件を網羅したことにはなりません。

GitHubのtokenと、AWSの認証を分ける

目的の違う三つの認証材料
材料用途
GITHUB_TOKENjobがGitHubの対象repositoryへ操作するための一時token。permissionsで絞る。
OIDCのID token外部サービスへjobの身元や文脈を伝える材料。取得にはid-token: writeが必要。
AWSの一時認証情報AWSがロール引受を許可した後、AWS APIを要求するために使う。
GitHub権限を読む断片:完全なworkflowではない
permissions:
  contents: read

ソースを読む検査なら必要な権限から考え、すべてへwrite-allを付けません。この断片では未指定の権限はnoneになり、OIDC tokenの取得許可もありません。実際の処理で必要なAPIを検討し、組織やイベントによる制約も確認します。GitHubへ書ける権限があっても、それはS3のPutObject許可ではありません。

非信頼の入力を、強い権限から隔てる

PRのコード、workflowの変更、タイトル等の入力は、審査するまで非信頼として扱います。特権を持つpull_request_targetやworkflow_runで、未審査PRのコードをcheckoutして実行する組合せは危険です。イベント名だけを見て安全と判断せず、その処理が読むコード・token・secret・接続先まで確認します。

secretは機密値であり、ログで必ず隠れるとは限りません。第三者actionも実行するコードなので、出所・内容・依存・必要権限を審査します。確認した完全なcommit SHAへ固定することは有用ですが、それだけで安全になるわけではありません。

チェック成功から、何が言える?

  1. どのrevisionと環境で、どんな条件を検査した記録かを読む。
  2. 成功・失敗・スキップ等の状態を見て、必要な検査が実際に走ったかを確認する。
  3. レビューの判断と、マージ後のビルド・配信・動作確認へ結論を広げない。

選択すると、正誤と理由が表示されます。

Actionsのworkflowを起動するeventに当たるのは?
答えと理由を読む

正解:PRの更新という出来事。 · eventは起動のきっかけです。jobやstepは実行側の構造です。

複数のjobを定義しました。実行順は?
答えと理由を読む

正解:依存関係や条件で決まる。stepは各job内にある。 · jobの並行性と、同じjob内のstepの順序を分けます。

GitHub上のソースを読む検査job。権限の考え方は?
答えと理由を読む

正解:必要なGitHub権限へ絞り、AWSやsecretの権限と分ける。 · contents: read等の必要権限を検討し、外部認証とは混同しません。

特権を持つworkflowで外部PRを扱うとき、避けるべきなのは?
答えと理由を読む

正解:未審査のPRコードをcheckoutして実行する。 · 非信頼コードへsecretや強いtoken、runnerの権限を渡す危険があります。

確認して、自分の言葉で説明する

  1. 一つのeventからjobとstepへ、役割を順に説明する。
  2. ソースの読取りに必要な権限と、配信の権限を分ける。
  3. 検査記録のrevisionと、後段の成果物を区別する。
理解を確かめる: Tのチェックが成功したら、Mの成果物は配信済み?

いいえ。取り込み後Mからのビルドと、その成果物の配信を別に確認します。

特定の対象へ定めた検査が終わったことは、後段の処理の実施を意味しません。

出典と確認した条件

説明に用いた一次資料を、確認した内容・条件と本文の参照箇所に分けてまとめています。専門家による監修・実環境での検証は行っていません。