Skip to main content
為了因應對 GitHub Actions 的攻擊或竄改風險,官方 Laravel 專案也採用了對 GitHub Actions 進行 pinning 的安全性對策。本頁將實務地說明套件開發者應實作的安全性對策。
本頁為套件開發基礎的姊妹頁。以熟悉 GitHub Actions 基本使用為前提。

GitHub Actions 的安全性風險

以 tag 為參考的危險性

一般而言,GitHub Actions 會像以下這樣以 tag 參考。
此方法的問題點:
  • tag 可移動 — tag 即便被刪除或重建,仍可持有相同名稱
  • 竄改風險 — 若儲存庫擁有者的帳號被劫持,惡意程式碼可被注入
  • 供應鏈攻擊 — 若相依的 action 遭攻擊,您的 workflow 也會受害

官方 Laravel 專案的對應

laravel/laravellaravel/framework 中,所有 action 都被 pinning 至 commit hash(SHA)。

Pinning 的實作策略

步驟 1:建立 Dependabot 設定檔

於套件的儲存庫建立 .github/dependabot.yml。可直接複製 Laravel 的檔案。
此檔案擔負下列職責:
  • 自動掃描 — 掃描 GitHub Actions 的新版本
  • 自動建立 PR — 若有更新可用,會自動建立更新 PR
  • 控制更新方式 — 未 pinning 的 action 以版本更新,已 pinning 者以 SHA 更新

步驟 2:將既有 action 改為 SHA pinning

將既有 workflow 內所有的 action 參考改為 SHA hash。可以 pinact 等工具自動化。

使用 pinact 工具自動化

手動修改

若無法使用 pinact,可從 GitHub 的 Lookup latest version 頁面查詢各 action 的 commit SHA,並手動替換。

步驟 3:啟用 Dependabot 設定

.github/dependabot.yml commit 並 push 至儲存庫後,Dependabot 便會自動開始掃描。

Dependabot 的自動更新機制

Dependabot 會依 dependabot.yml 的設定,套用不同的更新策略。

未 pinning 的 action

Dependabot 的更新:將版本範圍更新為新版本
此方式重便利性,可對應 tag 的移動,但仍留有安全性風險。

已 pinning 的 action

Dependabot 的更新:更新為新版本的 commit hash
此方式最為安全。即便為新版本,因參考的是 commit hash,故對抗竄改能力強。

Workflow 的實作範例

以下為使用多個 workflow 中的 action 的完整範例。

Dependabot 更新 PR 的處理

Dependabot 建立的更新 PR 可如下處理。

單一 action 的更新 PR

此類單純的更新可依下列方式處理:
  1. 確認 workflow 執行結果
  2. 確認是否有破壞性變更
  3. Merge 完成

安全性更新 PR

有關安全性修正的更新應優先 merge。

多個 action 的分組更新

若於 dependabot.yml 設定了 groups,多個 action 會於同一 PR 中更新。
將全部 action 更新集中於一個 PR,可減少 merge 次數。

Pinning 的優缺點

優點

缺點

安全性稽核 Checklist

以下為啟動新套件專案時的檢查清單。
  • 建立 .github/dependabot.yml
  • 將所有既有 action 進行 SHA pinning
  • pinact 或手動完成確認
  • 確認 workflow 可正常執行
  • 每週至少 1 次審查 Dependabot 的更新 PR
  • 安全性更新優先 merge
  • 新增 action 時務必以 SHA 參考
  • 每月 1 次確認所有 workflow 的狀態
  • 確認所有 action 參考皆為 SHA
  • 確認 Dependabot 已啟用
  • 確認過去 6 個月的 Dependabot PR 是否皆已 merge

相關頁面

套件開發基礎

說明以服務提供者為核心的 Laravel 套件開發方式。

套件的版本相容性管理

說明對應 Laravel 主版本更新的套件對應策略。
最後修改於 2026年8月2日