GitHub Actionsカスタムaction自作

なぜ自作するのか

[[CI/CD]] のワークフローは、放っておくと同じ手順の写しが増えます。Node の準備・キャッシュ・ビルド・成果物の検査という並びを、リポジトリごと・ジョブごとに書き写している状態です。

写しが増えると、直すときに全部を直さなければならないという問題が出ます。1か所直し忘れると、そのワークフローだけ古い挙動のまま残ります。カスタム action は、この繰り返しを名前の付いた1単位にまとめる仕組みです。

3つの実装形式

まず composite で足りないかを考えます。 既存のステップを並べるだけで済むなら、依存も起動時間も増えません。JavaScript が要るのは「条件によって挙動を変える」「結果を解析して次へ渡す」ような、YAMLでは書きにくい処理が入るときです。Docker は起動が最も遅いため、他で代替できないときの選択肢になります。

composite actionの形

action.yml を置いたディレクトリが、そのまま action になります。

# action/setup-and-build/action.yml
name: Setup and build
description: Node をセットアップして依存導入とビルドを行う
inputs:
  node-version:
    description: 使用する Node のバージョン
    default: '22'
outputs:
  dist-path:
    description: 生成物の出力先
    value: ${{ steps.build.outputs.path }}
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash
    - id: build
      run: |
        npm run build
        echo "path=dist" >> "$GITHUB_OUTPUT"
      shell: bash

呼び出し側は1行になります。

- uses: ./action/setup-and-build
  with:
    node-version: '22'

composite の run には shell の指定が必須です。 通常のワークフローでは省略できるため、ここで詰まることがよくあります。

設計で効くこと

• 入力と出力を明示する — 何を渡し何が返るかが action.yml に書かれていれば、中身を読まずに使えます
• リポジトリ内に置くか公開するか — 同一リポジトリ内なら相対パスで参照できます。複数リポジトリで使うなら別リポジトリへ切り出し、タグで版を固定します
• 版を固定する — @v4 のような可動タグは便利ですが、再現性が要る場面ではコミットハッシュで固定します
• 権限を最小にする — action に渡すトークンの権限は必要な範囲に絞ります。CI から書き込みができる状態は影響範囲が広くなります

初学者向けポイント

• ワークフローの一部を切り出す作業なので、まず動いているワークフローを用意してからまとめるのが早いです
• ローカルでの検証が難しいのが弱点です。検証用のブランチとワークフローを1つ用意し、そこで回して確かめます
• 手順が長くなると、失敗したときにどのステップで落ちたか分かりにくくなります。ステップに名前を付け、[[CI/CDパイプラインのゲートと並行制御]] の考え方で失敗を早い段階に寄せます

関連技術とのつながり

• [[CI/CD]] — カスタム action が組み込まれる先
• [[CI/CDパイプラインのゲートと並行制御]] — どの順で何を失敗させるかの設計
• [[YAML]] — action の定義とワークフローの記述形式
• [[Git]] — 版の固定はタグやコミットハッシュで行う
• [[Docker]] — 特定のツールチェーンが要るときの実装形式

Q: 繰り返すCI手順をカスタムactionにまとめる主な利点はどれ?
- [ ] ワークフローの実行が必ず速くなる
- [x] 直すときに1か所で済み、直し忘れによる挙動のずれを防げる
- [ ] YAMLを書かなくてよくなる
解説: 写しが増えると全部を直す必要が出ます。名前の付いた1単位にまとめることで修正箇所が集約されます。

Q: 既存のステップを並べ直すだけで済む場合に選ぶ形式はどれ?
- [x] composite action
- [ ] JavaScript action
- [ ] Docker action
解説: 依存も起動時間も増えません。条件分岐や結果の解析が要るときにJavaScript、特定のツールチェーンが要るときにDockerを選びます。

Q: composite action の `run` ステップで必須の指定はどれ?
- [ ] `working-directory`
- [x] `shell`
- [ ] `continue-on-error`
解説: 通常のワークフローでは省略できるため見落としやすく、composite で最初に詰まる箇所です。