ci.yml

# 主分支的驗證。
#
# 本倉庫只有 Markdown，沒有建置步驟——所以這裡驗的是**連結指不指得到東西**。
# 一條指向不存在檔案的相對連結，在 GitHub 上會安靜地 404，而 diff 上看不出來。
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review]
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

jobs:
  links:
    # **草稿 PR 也跑**（裁示 2026-08-21）：這裡原本有一條
    # `if: … || github.event.pull_request.draft == false`。見上方 `on:` 的註解。
    name: 內部連結
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      - name: 相對連結必須指得到檔案
        run: python3 tools/check-links.py

  # 安全掃描接在基礎驗證之後：基礎驗證紅燈時整組 **skipped**，而不是拿一份
  # 編譯不過的原始碼去跑掃描，再收到一顆與根因無關的第二紅燈。
  #
  # > **註**：這段文字到 2026-08-21 為止寫的是「**本倉庫是公開的，所以掃描與
  # > 基礎驗證同時起跑**，不等它綠燈」，理由是公開倉庫的 Actions 分鐘數不計費。
  # > 那個形狀在 2026-08-16 就被取代了，而**取代它的 `needs:` 一直都在**
  # > （就在下面幾行，還帶著自己的註解）——沒有跟上的只有這段文字。
  # >
  # > 它還聲明「兩種形狀是刻意的，不是漂移；判準見 workspace `AGENTS.md`
  # > §1.9.1」，而 §1.9.1 說的正好相反。**一段指著條文說自己不必照辦的註解，
  # > 比沒有註解更糟**：它讓讀者以為這裡已經對照過了，於是沒有人去比對。
  #
  # 掃描本身的定義在 `security.yml`，那支同時還掛著每週排程（**不**經過這道閘）。
  security:
    # **這一組在 PR 上全部會跑**（裁示 2026-08-21）。
    #
    # 2026-08-16 到 08-21 之間只有 Gitleaks 會動，其餘三種各自帶一條
    # `if: github.event_name != 'pull_request'`。當時的判準是「漏到 `main`
    # 之後要付什麼」：CodeQL／govulncheck／Trivy 找到的東西**修一次就結束**，
    # 在 PR 攔下與在 `main` 攔下代價一樣，所以省下每個 PR 數分鐘；只有
    # Gitleaks 代價不同（憑證已經在 git 歷史裡，刪掉不夠，**必須輪替**），
    # 所以它留在 PR。
    #
    # **前半仍然成立，後半不再是收益**：升上 Enterprise 之後分鐘數不是稀缺的
    # 東西了，而代價一直都在——一個在 `main` 才被攔下的問題，是一個**已經
    # 合併**的問題。判準因此收斂成一句：**CI 做得到的驗證，就讓它在合併前跑。**
    # 那三條 `if` 已於 2026-08-21 從 `security.yml` 拆掉。
    #
    # **`needs: [verify]` 那道閘留著，理由與成本無關**：建置壞掉時 CodeQL 的
    # autobuild 與 govulncheck 吐的是同一個編譯錯誤換一種包裝，多餘的紅燈會
    # 稀釋掉真的那一顆。每週排程**不**經過它（見上方 `on:` 的註解）。
    name: 安全掃描
    # 閘門對公開倉庫也成立了（裁示 2026-08-16）：掃描要先等基礎驗證綠。
    # 取代 workspace decisions/infrastructure/公開倉庫的掃描不經閘門.md
    needs: [links]
    uses: ./.github/workflows/security.yml
    permissions:
      contents: read
      # 呼叫端的權限是被呼叫 job 的**上限**，所以這裡要給到聯集。
      # CodeQL 與 Trivy 上傳 SARIF 要 security-events: write。
      security-events: write
    # 本倉庫的掃描不需要任何 secret，但呼叫端不宣告的話被呼叫端一個都拿不到，
    # 而形狀要與其餘十二個倉庫一致。
    secrets: inherit