32 lines
3.0 KiB
Markdown
32 lines
3.0 KiB
Markdown
---
|
||
name: spec-action-params
|
||
description: 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-shared: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 的傳入寫法：
|
||
|
||
```yaml
|
||
- uses: <owner>/<action>@<ref>
|
||
with:
|
||
token: ${{ secrets.MY_TOKEN }} # secrets 由呼叫端 workflow 傳入
|
||
registry: ${{ vars.MY_REGISTRY }} # vars 亦同
|
||
```
|