GitHub Actions Composite Actionで実現する再利用可能なワークフロー設計パターン¶

この記事の対象者

複数リポジトリで同じワークフローを繰り返し記述している中級者

この記事のポイント¶

Composite Actionの基本構造を実装
入力パラメータと出力値の管理
リポジトリ間での共有と更新戦略の確立

なぜこの問題が今重要か¶

GitHub Actionsの利用が拡大する中、ワークフローの重複コードが技術的負債化。Composite Actionによる標準化で、メンテナンス工数を70%削減できる実例が増加中。

解決ステップ概要¶

ステップ	内容	到達指標
1	action.ymlで基本構造定義	inputs/outputsの設定完了
2	共通処理のステップ実装	エラーハンドリング込み
3	別リポジトリから呼び出し	uses句での実行成功

ステップ1: action.ymlで基本構造定義¶

.github/actions/deploy-check/action.ymlを作成し、再利用可能な構造を定義：

name: 'Deploy Check'
description: 'デプロイ前の共通チェック処理'
inputs:
  node-version:
    description: 'Node.jsバージョン'
    required: false
    default: '20'
outputs:
  test-result:
    description: 'テスト結果'
    value: ${{ steps.test.outputs.result }}
runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}

ステップ2: 共通処理のステップ実装¶

エラーハンドリングとキャッシュ戦略を含む実装：

    - name: Cache dependencies
      uses: actions/cache@v4
      with:
        path: ~/.npm
        key: deps-${{ hashFiles('**/package-lock.json') }}

    - name: Run tests
      id: test
      shell: bash
      run: |
        npm ci
        npm test -- --json > test-results.json || echo "failed" > status.txt
        echo "result=$(cat status.txt || echo 'passed')" >> $GITHUB_OUTPUT

ステップ3: 別リポジトリから呼び出し¶

ワークフローでの使用例：

name: Deploy
on: push
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/deploy-check
        id: deploy-check
        with:
          node-version: '22'
      - run: echo "Test result: ${{ steps.deploy-check.outputs.test-result }}"

よくある落とし穴と対処¶

症状	原因	即時対処
action.yml not found	パス指定ミス	相対パス`./.github/actions/`を確認
shell未指定エラー	composite特有の制約	全runに`shell: bash`追加
出力値が空	GITHUB_OUTPUT未使用	`>> $GITHUB_OUTPUT`形式に修正

詳細設定（高度最適化）

### マーケットプレイス公開パターン別リポジトリでaction.ymlをルートに配置し、タグ付けでバージョン管理：

uses: org/action-repo@v1.2.0

### マトリックステスト対応

strategy:
  matrix:
    node: [18, 20, 22]