shared/skills/spec-action-params/SKILL.md

name, description

name	description
spec-action-params	JSC plugins 共用「Gitea／GitHub action 參數來源優先序」：開發 action 需要新參數時，先取 gitea/github context（composite）或 runner 注入的 GITHUB_*/GITEA_* 執行期環境變數（docker），取不到才經使用者同意新增 inputs；secrets/vars 在 action 內一律視為不可用，需要時宣告為 input 由呼叫端 workflow 傳入。當其他 skill 內文引用 spec-action-params 或 /jsc-generic:spec-action-params、或開發 composite/docker action 需要決定參數來源時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-action-params — 共用 action 參數來源優先序

開發 Gitea／GitHub action（composite 或 Docker 容器 action）過程中需要新的參數值時，依下列順序處理，前一項可取得就不往下。

1. 平台注入的 context／環境變數

• composite action：runs.steps 內可直接使用 ${{ gitea.* }}／${{ github.* }} context（Gitea 中兩者互為別名）。常用如 github.repository、github.ref_name、github.server_url、github.token、github.event.*。為同時相容 GitHub Actions，建議寫 github.*；run 腳本內可改讀同源的執行期環境變數（$GITHUB_REPOSITORY 等）。
• Docker 容器 action：action.yml 內 expression 幾乎只有 inputs／env context 可用，但 runner 會把 gitea.*／github.* 同源資訊以執行期環境變數注入容器 — Node 主程式讀 process.env.GITHUB_*（如 GITHUB_REPOSITORY、GITHUB_SERVER_URL、GITHUB_REF_NAME、GITHUB_EVENT_PATH；Gitea 亦提供 GITEA_* 同義變數），entrypoint.sh 內以 $GITHUB_* 讀取。為相容 GitHub，程式內建議讀 GITHUB_*。

2. 取不到 → 詢問使用者新增 inputs

• 以 AskUserQuestion 詢問使用者是否新增對應 input（名稱／description／required／default），經同意後才於 inputs 宣告。
• 取用方式：composite 於 step 內以 ${{ inputs.<name> }}；docker 容器內以 INPUT_<大寫名稱> 環境變數（Node 讀 process.env.INPUT_<NAME>）。
• 未經同意不得擅自更動 inputs／outputs 契約。

secrets／vars 一律視為不可用（不列入優先序）

• ${{ secrets.* }}／${{ vars.* }} context 在 composite action 的 action.yml 內於 GitHub 為官方明文不可用（inputs 的 default 也不能引用）；在 Docker 容器 action 的 runs.args／runs.env 內亦不可用（官方文件僅記載 inputs context 可用，runner 也不會把呼叫端 secrets 自動注入容器）。Gitea act_runner 未嚴格檢查 context 可用性、行為無保證。

• 為求兩邊相容，一律視為不可用 — 參數值本質上屬 secrets／vars 者，直接依第 2 項宣告為 input，回報時附上呼叫端 workflow 的傳入寫法：

  - uses: <owner>/<action>@<ref>
    with:
      token: ${{ secrets.MY_TOKEN }}     # secrets 由呼叫端 workflow 傳入
      registry: ${{ vars.MY_REGISTRY }}  # vars 亦同