> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub Actionsのピン留めとセキュリティ
> パッケージのサプライチェーン攻撃対策として、GitHub Actionsの依存関係をバージョンからSHAハッシュにピン留めする方法を、Dependabotの自動更新戦略を含めて解説します。
GitHubのアクションに対する攻撃や改ざんのリスクに対応するため、公式Laravelプロジェクトでも採用しているセキュリティ対策がGitHub Actionsのピン留め（pinning）です。このページでは、パッケージ開発者が実装すべきセキュリティ対策を実践的に解説します。
このページは[パッケージ開発の基礎](/jp/advanced/package-development)の姉妹ページです。GitHub Actionsの基本的な使用方法を前提としています。
## GitHub Actionsのセキュリティリスク
### タグベースの参照の危険性
通常、GitHub Actionsは以下のようにタグで参照されます。
```yaml theme={null}
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
```
このアプローチの問題点：
* **タグは移動可能** — タグは削除・再作成されても同じ名前を持てます
* **改ざんリスク** — リポジトリ所有者のアカウント乗っ取りで悪意あるコードを注入可能
* **サプライチェーン攻撃** — 依存するアクションが攻撃されると、あなたのワークフローが侵害されます
### 公式Laravelプロジェクトでの対応
[laravel/laravel](https://github.com/laravel/laravel) と [laravel/framework](https://github.com/laravel/framework) では、全てのアクションをコミットハッシュ（SHA）にピン留めしています。
```yaml theme={null}
# セキュアな参照方法
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab # v4
```
## ピン留めの実装戦略
### ステップ1：Dependabot設定ファイルの作成
パッケージのリポジトリに `.github/dependabot.yml` を作成します。Laravelのファイルをそのままコピーできます。
```yaml theme={null}
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](https://github.com/suzuki-shunsuke/pinact) などのツールで自動化できます。
#### pinactツールを使った自動化
```shell theme={null}
# ワークフロー内のアクションをSHAにピン留め
pinact run
```
#### 手動による変更
`pinact` が利用できない場合は、GitHubの [Lookup latest version](https://github.com/actions/checkout) ページから各アクションのコミットSHAを調べて手動で置き換えます。
```yaml theme={null}
# 変更前
- 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` の設定に基づいて、異なる更新戦略を適用します。
### ピン留めされていないアクション
```yaml theme={null}
# ピン留め前
- uses: actions/checkout@v4
```
Dependabotの更新：**バージョン範囲を新しいバージョンに更新**
```yaml theme={null}
# Dependabotが作成するPR
- uses: actions/checkout@v5
```
このアプローチは利便性重視で、タグの移動に対応できますが、セキュリティリスクは残ります。
### ピン留めされたアクション
```yaml theme={null}
# ピン留め後
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab # v4
```
Dependabotの更新：**新しいバージョンのコミットハッシュに更新**
```yaml theme={null}
# Dependabotが作成するPR
- uses: actions/checkout@f1d3225b54b677ba3e72df8c464cb6cf6dc1aebf # v4
```
このアプローチは最も安全です。新しいバージョンでも、コミットハッシュの参照なので改ざんに強いです。
## ワークフローの実装例
複数のワークフローでアクションを使用する場合の完全な例です。
```yaml theme={null}
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.yml` で `groups` を設定している場合、複数のアクションが一度のPRで更新されます。
```yaml theme={null}
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のメジャーバージョンアップへのパッケージ対応戦略を解説します。