GitHub Actions で、人が見る前に落ちるものを落とす

第8回で、プルリクエストは止まる場所だと書きました。止まっている間に何をするかは、そのとき人の目に任せていました。

この回で、その一部を機械に移します。機械で判定できることを機械にやらせておけば、人の目は機械が気づけないところに使えます。

何を機械に任せられるか

判断の線引きは単純です。答えが一意に決まるものは機械、決まらないものは人。

型の不一致は一意に決まります。書式の乱れも決まります。テストが通るかどうかも決まります。これらは全部、機械のほうが速くて正確です。

一方、その設計でよいか、この変更が利用者にとって意味があるか、説明が分かりやすいかは決まりません。人が読むしかない。

AIに書かせる量が増えると、この区別の価値が上がります。出てくる量が増えても、人が読む速さは変わらないからです。読む対象を減らす手段として、機械の検査が効いてきます。

実際のワークフロー

BenriWorks のブログで動いているものを、そのまま載せます。

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  ci:
    name: typecheck / lint / test / content / build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: 依存関係のインストール
        run: npm ci

      - name: TypeScript型検査
        run: npm run typecheck

      - name: ESLint
        run: npm run lint

      - name: 単体テスト
        run: npm run test

      - name: コンテンツスキーマ・slug重複・関連先・画像存在検証
        run: npm run validate:content

      - name: 内部リンク・画像参照検査
        run: npm run check:links

      - name: Production build
        run: npm run build

読み方を上から追います。

on が、いつ走らせるかです。プルリクエストが作られたときと更新されたとき、そして本番用ブランチへ反映されたとき。第8回で決めた「止まる場所」に合わせています。

runs-on が、どんな環境で走らせるかです。GitHub 側が用意する使い捨ての機械で、毎回きれいな状態から始まります。だから、手元の環境に残っているものに依存していないかが、この仕組みで自動的に確かめられます。

steps が、上から順に実行される作業です。1つでも失敗すると、そこで止まって全体が失敗になります。

並べる順番で待ち時間が変わる

手順の並びには意図があります。速くて落ちやすいものが前、遅いものが後ろです。

型検査は数十秒で終わり、よく落ちます。ビルドは数分かかります。型が通らないコードはビルドも通らないので、先に型検査で落としておけば、ビルドの時間を使わずに済みます。

同じ理屈で、テストは検査系の後ろに置いています。書式の乱れで落ちるなら、テストを走らせる前に分かったほうが速い。

この並びは、開発の体感をかなり変えます。うまくいかない変更ほど早く結果が返るので、待ち時間の多くが「通る変更を待つ時間」になります。

自分の仕事に合わせた検査を足す

上のワークフローの中に、一般的でない項目が2つあります。validate:content と check:links です。

これはメディアサイトの仕事に特有の検査です。記事の設定項目が仕様どおりか、記事の識別子が重複していないか、参照先の記事が実在するか、指定した画像ファイルが実際に置かれているか。内部リンクの検査は、リンク先が存在しないページを指していないかを見ています。

どちらも、書かれた文章の良し悪しとは無関係な、機械で決まる検査です。そして、人が一番見落としやすい種類でもあります。記事を読み直すとき、リンク先を1つずつ開いて確かめる人はいません。

自分の仕事で「毎回確認するのを忘れて、あとで困ること」が何かを考えると、足すべき検査が見えてきます。BenriWorks の場合はリンク切れと画像の欠落でした。

似た例として、別のアプリでは、アクセス解析のタグが正しい文字列として書き出されるかを検査する項目を足しました。実際に構文の誤りで計測が止まったことがあり、その再発を止めるために入れたものです。事故が起きたら検査を1つ足すという進め方は、第9回の規約の育て方と同じです。

Codex 側の検査との関係

AGENTS.md に書いた検査コマンドと、ここで走らせる検査は、同じものを指しています。

役割は違います。Codex 側の検査は、書いた本人が手元で確かめるものです。GitHub Actions の検査は、手元の環境に依存しない状態で確かめるものです。

食い違いが出たときに、その差が情報になります。手元では通るのに GitHub Actions で落ちるなら、手元の環境に何かが残っています。入れたはずの依存が記録されていない、生成されるはずのファイルが手で置かれている、といった原因が典型です。

通らないと反映できない状態にする

検査を作っても、落ちたまま反映できるなら意味が半分になります。

第8回で触れたブランチの保護設定に、ここで1つ足します。指定した検査が通っていることを、反映の条件にする設定です。これを入れると、落ちているプルリクエストはマージのボタンが押せなくなります。

自分で運用していると、「今回は急ぐから」と通してしまう場面が必ず来ます。ボタンが押せなければ、その選択肢自体がなくなります。判断の機会を減らすことが、仕組みの一番の効き目です。

落ちたときに何をするか

検査が落ちたら、失敗した手順の記録を読みます。GitHub の画面で、落ちた項目を開くと出力が出ます。

この出力を Codex に渡すのが一番速い直し方です。エラーの文面をそのまま貼って、直してもらいます。第6回の3つでいえば、エラーの出力が文脈にあたります。

ただし、落ちた理由が分からないまま直してもらわないでください。型検査が落ちたときに、型の宣言を緩めて通すこともできます。それは通っただけで、直っていません。出力を自分でも読み、何が起きたかを理解してから渡してください。理解できないなら、そこは Codex に説明させる依頼を先に出します。

次の回

ここまでは、手元で動かした Codex の結果を GitHub へ持っていく流れでした。

第14回では、順番を逆にします。GitHub の上で Codex を動かし、プルリクエストのレビューや、手元を経由しない作業を任せる方法です。

参照した情報

• GitHub Actions のワークフロー構文に関する公式ドキュメント（docs.github.com）
• 引用したワークフローは BenriWorks のブログリポジトリで実際に動いているもの