Secrets 管理

GitHub Actions 中環境變數與 Secrets 的設定與使用。

什麼是 Secrets

Secrets 是加密的環境變數,用於儲存敏感資訊（如 API 金鑰、密碼、token）,不會暴露在日誌或程式碼中。

Secrets 類型

Repository Secrets

儲存在單一儲存庫層級,僅該儲存庫的 workflows 可存取。

設定路徑:Settings → Secrets and variables → Actions → New repository secret

Organization Secrets

儲存在組織層級,可供組織內多個儲存庫共用。

存取控制:可限制哪些儲存庫可存取特定 secret。

Environment Secrets

與 GitHub Environments 綁定,用於區分不同部署環境（如 staging、production）。

使用 Secrets

在 Workflow 中引用

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy with API key
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: ./deploy.sh

Secrets 命名規則

• 只能包含字母、數字、底線（_）
• 不能以 GITHUB_ 開頭（保留前綴）
• 大小寫敏感

環境變數

預定義環境變數

自訂環境變數

Workflow 層級

env:
  NODE_ENV: production
  APP_VERSION: 1.0.0

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build app
        run: npm run build

Job 層級

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      BUILD_ENV: staging
    steps:
      - name: Build app
        run: npm run build

Step 層級

steps:
  - name: Run tests
    env:
      TEST_DATABASE_URL: ${{ secrets.TEST_DB_URL }}
    run: npm test

環境變數優先級

1. Step 層級 env ← 最高優先級
2. Job 層級 env
3. Workflow 層級 env
4. 系統環境變數 ← 最低優先級

Secrets 安全最佳實踐

不要在日誌中輸出 Secrets

❌ 錯誤做法:

- name: Debug
  run: echo "API Key: ${{ secrets.API_KEY }}"  # 會被記錄

✅ 正確做法:

- name: Debug
  run: echo "API Key: ***"  # GitHub Actions 會自動遮蔽 secrets

使用 Environment Protection Rules

對於生產環境,啟用 environment protection:

• 需要審核者批准
• 限制可部署的分支
• 設定部署延遲

定期輪換 Secrets

定期更新 API 金鑰和 token,降低洩漏風險。

GITHUB_TOKEN 權限控制

預設權限

GitHub Actions 自動提供 GITHUB_TOKEN,預設權限:

• contents: read
• metadata: read

自訂權限

permissions:
  contents: write      # 允許推送程式碼
  pull-requests: write # 允許建立 PR
  issues: write        # 允許建立 issue

最小權限原則

僅授予 workflow 所需的最小權限:

permissions:
  contents: read  # 僅讀取

Secrets 與環境變數比較