メインコンテンツへスキップ
GitHubのアクションに対する攻撃や改ざんのリスクに対応するため、公式Laravelプロジェクトでも採用しているセキュリティ対策がGitHub Actionsのピン留め(pinning)です。このページでは、パッケージ開発者が実装すべきセキュリティ対策を実践的に解説します。
このページはパッケージ開発の基礎の姉妹ページです。GitHub Actionsの基本的な使用方法を前提としています。

GitHub Actionsのセキュリティリスク

タグベースの参照の危険性

通常、GitHub Actionsは以下のようにタグで参照されます。
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
このアプローチの問題点:
  • タグは移動可能 — タグは削除・再作成されても同じ名前を持てます
  • 改ざんリスク — リポジトリ所有者のアカウント乗っ取りで悪意あるコードを注入可能
  • サプライチェーン攻撃 — 依存するアクションが攻撃されると、あなたのワークフローが侵害されます

公式Laravelプロジェクトでの対応

laravel/laravellaravel/framework では、全てのアクションをコミットハッシュ(SHA)にピン留めしています。
# セキュアな参照方法
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

ピン留めの実装戦略

ステップ1:Dependabot設定ファイルの作成

パッケージのリポジトリに .github/dependabot.yml を作成します。Laravelのファイルをそのままコピーできます。
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 5
    groups:
      github-actions:
        patterns:
          - "*"
このファイルは以下の役割を担います:
  • 自動スキャン — GitHub Actionsの新しいバージョンをスキャン
  • 自動PR作成 — 更新が利用可能な場合、アップデートPRを自動作成
  • 更新方法の制御 — ピン留めされていないアクションはバージョンで、ピン留めされたアクションはSHAで更新

ステップ2:既存アクションをSHAにピン留める

既存のワークフロー内のすべてのアクション参照をSHAハッシュに変更します。これは pinact などのツールで自動化できます。

pinactツールを使った自動化

# ワークフロー内のアクションをSHAにピン留め
pinact run

手動による変更

pinact が利用できない場合は、GitHubの Lookup latest version ページから各アクションのコミットSHAを調べて手動で置き換えます。
# 変更前
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
  with:
    php-version: ${{ matrix.php }}

# 変更後
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
- uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
  with:
    php-version: ${{ matrix.php }}

ステップ3:Dependabotの設定を有効化

.github/dependabot.yml をリポジトリにコミットしてプッシュすると、Dependabotが自動的にスキャンを開始します。

Dependabotによる自動更新メカニズム

Dependabotは dependabot.yml の設定に基づいて、異なる更新戦略を適用します。

ピン留めされていないアクション

# ピン留め前
- uses: actions/checkout@v4
Dependabotの更新:バージョン範囲を新しいバージョンに更新
# Dependabotが作成するPR
- uses: actions/checkout@v5
このアプローチは利便性重視で、タグの移動に対応できますが、セキュリティリスクは残ります。

ピン留めされたアクション

# ピン留め後
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
Dependabotの更新:新しいバージョンのコミットハッシュに更新
# Dependabotが作成するPR
- uses: actions/checkout@f1d3225b54b677ba3e72df8c464cb6cf6dc1aebf  # v4
このアプローチは最も安全です。新しいバージョンでも、コミットハッシュの参照なので改ざんに強いです。

ワークフローの実装例

複数のワークフローでアクションを使用する場合の完全な例です。
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      fail-fast: false
      matrix:
        php: [8.2, 8.3, 8.4]
        laravel: ["^12.0", "^13.0"]

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
        with:
          fetch-depth: 0

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip, intl, sqlite3
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" \
                           --no-interaction --no-update
          composer update --prefer-dist --no-interaction

      - name: Run tests
        run: vendor/bin/pest

  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: "8.4"
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: composer install --prefer-dist --no-interaction

      - name: Run static analysis
        run: vendor/bin/phpstan

Dependabotの更新PR対応

Dependabotが作成するアップデートPRは以下のように対応します。

単一アクションの更新PR

Bump shivammathur/setup-php from v1 to v2
このような単純なアップデートは以下のように対応:
  1. ワークフロー実行結果を確認
  2. 破壊的変更がないか確認
  3. マージして完了

セキュリティアップデートPR

[SECURITY] Bump actions/checkout to a5ac7e51b41094c7fcab2042361574b0021804ab
セキュリティ修正に関する更新は優先的にマージします。

複数アクションのグループ更新

dependabot.ymlgroups を設定している場合、複数のアクションが一度のPRで更新されます。
groups:
  github-actions:
    patterns:
      - "*"
全アクション更新を1つのPRにまとめることで、マージ回数を減らせます。

ピン留めのメリットとデメリット

メリット

メリット説明
サプライチェーン攻撃対策特定のコミットハッシュを参照するため、アクションの改ざんに対抗できる
監査可能性各アクションがいつどのバージョンから更新されたかを追跡できる
明示的な更新Dependabotが更新を提案する形式なので、人間のレビューを必ず経由する
再現性同じコミットハッシュで実行すれば、完全に同じ環境が再現される

デメリット

デメリット対処方法
手作業の初期セットアップpinact ツールで自動化
更新管理の手間増加Dependabotで自動PR作成するため、実装コスト最小化
読みにくさコメントでバージョンを併記して可読性確保

セキュリティ監査チェックリスト

新しいパッケージプロジェクトを開始する場合のチェックリストです。
  • .github/dependabot.yml を作成
  • 既存アクションすべてをSHAにピン留め
  • pinact または手動で確認完了
  • ワークフローが正常に実行されることを確認
  • Dependabotの更新PRを週1回以上レビュー
  • セキュリティ更新は優先的にマージ
  • 新しいアクション追加時は必ずSHAで参照
  • 月に1回、全ワークフローの状態を確認
  • すべてのアクション参照がSHAになっているか確認
  • Dependabotが有効になっているか確認
  • 過去6ヶ月のDependabotのPRが全てマージされているか確認

関連ページ

パッケージ開発の基礎

サービスプロバイダーを核としたLaravelパッケージの開発方法を解説します。

パッケージのバージョン互換性管理

Laravelのメジャーバージョンアップへのパッケージ対応戦略を解説します。
最終更新日 2026年6月13日