name: 'Gitea Composite Template'      # 必填
description: 'Gitea Composite 範本'    # 必填
author: 'Jeffery'                     # 選填

inputs:                               # 選填，定義輸入參數
  message:
    description: '輸入訊息'
    required: false
    default: 'Hello, World!'

outputs:                              # 選填，定義輸出
  message:
    description: '輸出訊息'
    value: ${{ steps.exchange.outputs.message }}   # composite 必填 value

runs:                                 # 必填
  using: 'composite'                  # 必填，固定為 composite
  steps:                              # 必填，至少一個 step
  - name: Exchange
    id: exchange
    env:                              # env 只能設在 step 層
      MESSAGE: ${{ inputs.message }}
    run: echo "message=$MESSAGE" >> "$GITHUB_OUTPUT"
    shell: bash                       # 用 run 時強制必填

branding:                             # 選填（Marketplace 用，Gitea 內部可省略）
  icon: 'activity'
  color: 'blue'

📌 檔名只能是 action.yml 或 action.yaml，放在 action repo 根目錄。

頂層參數

參數	必填	說明
`name`	✅	Action 名稱。
`description`	✅	Action 簡短說明。
`author`	❌	作者名稱。
`inputs`	❌	輸入參數定義（見下）。
`outputs`	❌	輸出定義（見下）。
`runs`	✅	執行設定；composite 固定用 `using: 'composite'` + `steps`。
`branding`	❌	Marketplace 顯示用的 `icon` 與 `color`。

`inputs`（輸入參數）

每個 input 是 inputs.<input_id> 底下的一組設定：

欄位	必填	說明
`description`	✅	參數說明。
`required`	❌	是否必填，布林值，預設 `false`。
`default`	❌	預設值；呼叫端沒傳時採用。只能是字串。
`deprecationMessage`	❌	標記此 input 已棄用，使用時發出警告訊息。

在 composite 內取用 input → 用 ${{ inputs.<input_id> }}：

inputs:
  message:
    description: '輸入訊息'
    required: false
    default: 'Hello, World!'

呼叫端傳值（用 with）：

- uses: ./
  with:
    message: 'Hi there'

⚠️ 重要差異：composite action 不會自動產生 INPUT_<NAME> 環境變數（Docker / JS action 才有）。在 composite 內只能用 ${{ inputs.<id> }} context 取值；若要當環境變數用，需自己在 step 的 env: 對應一次（如範例的 MESSAGE）。

input 值一律是字串；數字、布林傳進來也會變字串（例如 "true"），比較時要留意。

`outputs`（輸出）

composite action 的 output 與 JavaScript / Docker action 不同：必須額外提供 value，明確指定值從哪個 step 來。

欄位	必填	說明
`description`	✅	輸出說明。
`value`	✅（composite）	輸出值，通常對應某個 step 的 output：`${{ steps.<id>.outputs.<name> }}`。

step 內設定 output → 寫入 $GITHUB_OUTPUT 檔案：

outputs:
  message:
    description: '輸出訊息'
    value: ${{ steps.exchange.outputs.message }}
runs:
  using: 'composite'
  steps:
  - id: exchange                                   # 一定要有 id 才能被 value 引用
    run: echo "message=Hello" >> "$GITHUB_OUTPUT"
    shell: bash

呼叫端取用 output：

- id: composite-template
  uses: ./
- run: echo "${{ steps.composite-template.outputs.message }}"

`runs.steps`（步驟）

composite 的核心。steps 是陣列，每個 step 支援下列欄位：

欄位	必填	說明
`run`	二選一	要執行的 shell 指令；與 `uses` 二擇一。
`shell`	✅（用 `run` 時）	用 `run` 時強制必填（見下方限制）。例：`bash`、`pwsh`、`sh`、`python`。
`uses`	二選一	呼叫另一個 action；與 `run` 二擇一。
`with`	❌	搭配 `uses`，傳入該 action 的 inputs。
`name`	❌	step 顯示名稱。
`id`	❌	step 識別碼；要引用該 step 的 outputs 時必填。
`env`	❌	此 step 的環境變數（只能設在 step 層，不能設在 `runs` 層）。
`working-directory`	❌	此 step 的工作目錄。
`if`	❌	條件式，決定是否執行此 step。
`continue-on-error`	❌	失敗時是否繼續，布林值。

Composite action 的限制與注意事項

以下是實務上最容易踩雷的地方：

runs.env 不支援 環境變數不能設在 runs: 層，只能設在個別 step 的 env:（或呼叫端的 job / workflow 層）。設在 runs.env 會被直接忽略，變數會是空的。

# ❌ 錯誤：runs 層 env 會被忽略
runs:
  using: 'composite'
  env:
    MESSAGE: ${{ inputs.message }}

# ✅ 正確：設在 step 上
runs:
  using: 'composite'
  steps:
  - env:
      MESSAGE: ${{ inputs.message }}
    run: echo "$MESSAGE"
    shell: bash

每個 run step 都必須指定 shell 在一般 workflow 裡 shell 可省略，但 composite action 內強制必填，否則會報錯。
outputs 必須明確給 value 不像 JS/Docker action，composite 的 output 一定要用 value: ${{ steps.<id>.outputs.<name> }} 指定來源。
input 用 inputs context，沒有 INPUT_ 環境變數 如前述，composite 內取 input 只能 ${{ inputs.<id> }}，不會有 INPUT_MESSAGE 這種環境變數。
不能直接使用 secrets composite action 內無法直接讀 ${{ secrets.* }}，需要由呼叫端透過 inputs 傳進來。
不支援 pre / post composite / 本機（local）action 不支援 runs.pre、runs.post（那是 JS action 專屬）。需要前置/後置動作就用一般的 step 排序。
父層的 if 不會傳遞進來 呼叫端 step 上的 if 只決定「要不要跑這個 composite」；一旦進入 composite，內部 step 是乾淨狀態，父層條件不會自動套用到每個子 step。子 step 要條件判斷需各自寫 if。
step 之間共享環境變數 / PATH 在某個 step 寫入 $GITHUB_ENV、$GITHUB_PATH 的值，可被同一個 composite 內後續 step使用。
引用 action 內附檔案用 ${{ github.action_path }} 要跑 action 目錄裡自帶的腳本時，用 $GITHUB_ACTION_PATH / ${{ github.action_path }} 定位，不要用相對路徑（執行時工作目錄是呼叫端的 repo，不是 action 目錄）。
```
- run: "$GITHUB_ACTION_PATH/scripts/run.sh"
  shell: bash
```
shell: bash 的預設旗標 shell: bash 實際會展開成 bash --noprofile --norc -e -o pipefail {0}：
- -e：任一指令失敗立即中止 step。
- -o pipefail：pipe 中任一段失敗即視為失敗。
- 若某行預期可能失敗又不想讓 step 掛掉，加上 || true。
可巢狀，但子 action 繼承有規則 composite 內可用 uses 再呼叫其他 action；巢狀 step 可存取上層的 input，也可覆寫。避免無限遞迴。

Gitea vs GitHub Actions 差異

Gitea Actions 不是 GitHub Actions 的 100% 複製品。撰寫 action 時特別注意：

項目	Gitea 行為
表達式函式	依官方比較文件，僅保證支援 `always()`；`success()` / `failure()` / `cancelled()` / `hashFiles()` 等其他函式視 `act` runner 版本而定，不保證可用——寫 `if:` 前先在測試機驗證。
`uses` 支援絕對 URL	可寫 `uses: https://github.com/actions/checkout@v4` 或 `uses: http://your_gitea/owner/repo@branch`，不限同站 action。
composite 內用絕對 URL	⚠️ 部分 runner 不支援在 composite action 裡用絕對 URL 的 `uses`；絕對 URL 建議只用在 workflow step。
Go actions	Gitea 額外支援 `using: 'go'` 寫 Go action（GitHub 沒有）。
context 檢查較寬鬆	Gitea 不檢查 context 可用性，`env` context 可用在比 GitHub 更多的位置（但不代表可攜，跨到 GitHub 會失敗）。
被忽略的 job 欄位	`jobs.<job_id>.timeout-minutes`、`jobs.<job_id>.continue-on-error`、`jobs.<job_id>.environment` 會被忽略。
`runs-on`	只接受簡單格式 `runs-on: xyz` 或 `runs-on: [xyz]`，不支援複雜表達式。
annotations / problem matchers	不支援，會被忽略。
`permissions` scope	支援 `permissions`，但沒有 GitHub 專屬的 `statuses` / `checks` / `deployments` / `id-token` / `security-events` / `pages`；Gitea 有自己的 `code` / `releases` / `wiki` / `projects`。

上表以 Gitea 官方文件為準；act runner 持續更新，部分限制（尤其表達式函式）可能隨版本放寬，仍以你環境的實測為準。

本 repo 範例對照

Action 定義：action.yml
CI 呼叫範例：.gitea/workflows/ci.yaml

CI 中先呼叫本 action、再取用其 output：

- name: Testing
  id: composite-template
  uses: ./
- name: Feedback
  run: echo "${{ steps.composite-template.outputs.message }}"

readme.md Unescape Escape

Gitea Composite Action 範本

目錄

完整結構總覽

頂層參數

inputs（輸入參數）

outputs（輸出）

runs.steps（步驟）