From 5e2c0853a099b660b17799359d2ce7a2c387baf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=B3=BB=E7=B5=B1=E7=AE=A1=E7=90=86=E5=93=A1?= <1+admin@noreply.localhost> Date: Wed, 1 Jul 2026 06:42:47 +0000 Subject: [PATCH 1/9] =?UTF-8?q?=E5=88=AA=E9=99=A4=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 271 ------------------------------------------------------ 1 file changed, 271 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index b118d6e..0000000 --- a/README.md +++ /dev/null @@ -1,271 +0,0 @@ -# Gitea Composite Action 範本 - -Composite（複合）action 讓你把多個 step 打包成一個可重用的 action，用 YAML 直接組合 shell 指令或呼叫其他 action，不需要寫 JavaScript 或包 Docker image。 - -本文件整理 `action.yml` 中**所有可用參數、說明與限制**，並特別標出 **Gitea 與 GitHub Actions 的差異**。範例皆對應本 repo 的 [`action.yml`](./action.yml)。 - -> 語法基準：Gitea Actions 以相容 GitHub Actions metadata 語法為目標，但兩者有明確差異（見「Gitea vs GitHub」章節）。Gitea 端的行為亦受底層 [`act`](https://gitea.com/gitea/act) runner 版本影響，實作前建議以測試機驗證。 - ---- - -## 目錄 - -- [完整結構總覽](#完整結構總覽) -- [頂層參數](#頂層參數) -- [`inputs`（輸入參數）](#inputs輸入參數) -- [`outputs`（輸出）](#outputs輸出) -- [`runs.steps`（步驟）](#runssteps步驟) -- [Composite action 的限制與注意事項](#composite-action-的限制與注意事項) -- [Gitea vs GitHub Actions 差異](#gitea-vs-github-actions-差異) -- [本 repo 範例對照](#本-repo-範例對照) -- [參考來源](#參考來源) - ---- - -## 完整結構總覽 - -```yaml -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.` 底下的一組設定： - -| 欄位 | 必填 | 說明 | -|------|------|------| -| `description` | ✅ | 參數說明。 | -| `required` | ❌ | 是否必填，布林值，預設 `false`。 | -| `default` | ❌ | 預設值；呼叫端沒傳時採用。**只能是字串**。 | -| `deprecationMessage` | ❌ | 標記此 input 已棄用，使用時發出警告訊息。 | - -**在 composite 內取用 input** → 用 `${{ inputs. }}`： - -```yaml -inputs: - message: - description: '輸入訊息' - required: false - default: 'Hello, World!' -``` - -**呼叫端傳值**（用 `with`）： - -```yaml -- uses: ./ - with: - message: 'Hi there' -``` - -> ⚠️ **重要差異**：composite action **不會**自動產生 `INPUT_` 環境變數（Docker / JS action 才有）。在 composite 內**只能**用 `${{ inputs. }}` context 取值；若要當環境變數用，需自己在 step 的 `env:` 對應一次（如範例的 `MESSAGE`）。 -> -> input 值一律是**字串**；數字、布林傳進來也會變字串（例如 `"true"`），比較時要留意。 - ---- - -## `outputs`（輸出） - -composite action 的 output **與 JavaScript / Docker action 不同**：**必須**額外提供 `value`，明確指定值從哪個 step 來。 - -| 欄位 | 必填 | 說明 | -|------|------|------| -| `description` | ✅ | 輸出說明。 | -| `value` | ✅（composite） | 輸出值，通常對應某個 step 的 output：`${{ steps..outputs. }}`。 | - -**step 內設定 output** → 寫入 `$GITHUB_OUTPUT` 檔案： - -```yaml -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**： - -```yaml -- 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 的限制與注意事項 - -以下是實務上最容易踩雷的地方： - -1. **`runs.env` 不支援** - 環境變數**不能**設在 `runs:` 層，只能設在個別 step 的 `env:`（或呼叫端的 job / workflow 層）。設在 `runs.env` 會被直接忽略，變數會是空的。 - - ```yaml - # ❌ 錯誤：runs 層 env 會被忽略 - runs: - using: 'composite' - env: - MESSAGE: ${{ inputs.message }} - - # ✅ 正確：設在 step 上 - runs: - using: 'composite' - steps: - - env: - MESSAGE: ${{ inputs.message }} - run: echo "$MESSAGE" - shell: bash - ``` - -2. **每個 `run` step 都必須指定 `shell`** - 在一般 workflow 裡 `shell` 可省略，但 composite action 內**強制必填**，否則會報錯。 - -3. **outputs 必須明確給 `value`** - 不像 JS/Docker action，composite 的 output 一定要用 `value: ${{ steps..outputs. }}` 指定來源。 - -4. **input 用 `inputs` context，沒有 `INPUT_` 環境變數** - 如前述，composite 內取 input 只能 `${{ inputs. }}`，不會有 `INPUT_MESSAGE` 這種環境變數。 - -5. **不能直接使用 `secrets`** - composite action 內**無法**直接讀 `${{ secrets.* }}`，需要由呼叫端透過 `inputs` 傳進來。 - -6. **不支援 `pre` / `post`** - composite / 本機（local）action **不支援** `runs.pre`、`runs.post`（那是 JS action 專屬）。需要前置/後置動作就用一般的 step 排序。 - -7. **父層的 `if` 不會傳遞進來** - 呼叫端 step 上的 `if` 只決定「要不要跑這個 composite」；一旦進入 composite，內部 step 是**乾淨狀態**，父層條件不會自動套用到每個子 step。子 step 要條件判斷需各自寫 `if`。 - -8. **step 之間共享環境變數 / PATH** - 在某個 step 寫入 `$GITHUB_ENV`、`$GITHUB_PATH` 的值，可被**同一個 composite 內後續 step**使用。 - -9. **引用 action 內附檔案用 `${{ github.action_path }}`** - 要跑 action 目錄裡自帶的腳本時，用 `$GITHUB_ACTION_PATH` / `${{ github.action_path }}` 定位，不要用相對路徑（執行時工作目錄是呼叫端的 repo，不是 action 目錄）。 - - ```yaml - - run: "$GITHUB_ACTION_PATH/scripts/run.sh" - shell: bash - ``` - -10. **`shell: bash` 的預設旗標** - `shell: bash` 實際會展開成 `bash --noprofile --norc -e -o pipefail {0}`： - - `-e`：任一指令失敗立即中止 step。 - - `-o pipefail`：pipe 中任一段失敗即視為失敗。 - - 若某行預期可能失敗又不想讓 step 掛掉，加上 `|| true`。 - -11. **可巢狀，但子 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..timeout-minutes`、`jobs..continue-on-error`、`jobs..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`](./action.yml) -- CI 呼叫範例：[`.gitea/workflows/ci.yaml`](./.gitea/workflows/ci.yaml) - -CI 中第 3 步呼叫本 action、第 4 步取用其 output： - -```yaml -- name: 3. Testing - id: composite-template - uses: ./ -- name: 4. Feedback - run: echo "${{ steps.composite-template.outputs.message }}" -``` - ---- - -## 參考來源 - -- [GitHub Actions — Metadata syntax for actions](https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax) -- [Gitea — Compared to GitHub Actions](https://docs.gitea.com/usage/actions/comparison) -- [Gitea — Actions FAQ](https://docs.gitea.com/usage/actions/faq) -- [actions/runner — Composite run steps ADR](https://github.com/actions/runner/blob/main/docs/adrs/0549-composite-run-steps.md) -- [actions/runner#665 — INPUT_* env vars missing in composite actions](https://github.com/actions/runner/issues/665) From b16e7ec0aa9d08bdb9f492703fea35ea84ecea4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=B3=BB=E7=B5=B1=E7=AE=A1=E7=90=86=E5=93=A1?= <1+admin@noreply.localhost> Date: Wed, 1 Jul 2026 06:57:49 +0000 Subject: [PATCH 2/9] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20action.yml?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- action.yml | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/action.yml b/action.yml index 79b490f..d4c2888 100644 --- a/action.yml +++ b/action.yml @@ -1,11 +1,10 @@ -name: 'Gitea Composite Template' -description: 'Gitea Composite 範本' +name: 'Codex CLI' +description: '安裝 Codex CLI 工具' author: 'Jeffery' inputs: - message: - description: '輸入訊息' - required: false - default: 'Hello, World!' + oauth: + description: '透過 OAuth 登入 ChatGPT 產生驗證檔，經過 base64 編碼' + required: true outputs: message: description: '輸出訊息' @@ -13,10 +12,12 @@ outputs: runs: using: 'composite' steps: - - name: Exchange - id: exchange + - name: Setup Codex env: - MESSAGE: ${{ inputs.message }} - run: | - echo "message=$MESSAGE" >> "$GITHUB_OUTPUT" + CODEX_NON_INTERACTIVE: 1 + run: curl -fsSL https://chatgpt.com/codex/install.sh | sh shell: bash + - name: Login Codex with OAuth + env: + OAUTH: ${{ inputs.oauth }} + run: echo $OAUTH | base64 --decode > ~/.codex/auth.json \ No newline at end of file From e625ad77f5939c447c77f5a7dbb0b5e125867375 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=B3=BB=E7=B5=B1=E7=AE=A1=E7=90=86=E5=93=A1?= <1+admin@noreply.localhost> Date: Wed, 1 Jul 2026 07:06:06 +0000 Subject: [PATCH 3/9] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20.gitea/workflows/ci.ya?= =?UTF-8?q?ml?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index ac0a15e..78b70a9 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -14,8 +14,10 @@ jobs: - name: Source Code checkout uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }} - name: Build - id: build uses: ./ + - name: Execute + id: execute + run: echo "do something..." test: name: 2. TEST runs-on: ubuntu From df2b2759f348894ccf85efa3381dabe4af8b419f Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 1 Jul 2026 15:11:10 +0800 Subject: [PATCH 4/9] =?UTF-8?q?chore(ci):=20Execute=20=E9=9A=8E=E6=AE=B5?= =?UTF-8?q?=E5=91=BC=E5=8F=AB=20codex=20=E8=87=AA=E6=88=91=E4=BB=8B?= =?UTF-8?q?=E7=B4=B9=E4=B8=A6=E8=BC=B8=E5=87=BA=E8=87=B3=20message?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 78b70a9..02ac9ef 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -9,7 +9,7 @@ jobs: name: 1. BUILD runs-on: ubuntu outputs: - message: ${{ steps.build.outputs.message }} + message: ${{ steps.execute.outputs.message }} steps: - name: Source Code checkout uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }} @@ -17,7 +17,14 @@ jobs: uses: ./ - name: Execute id: execute - run: echo "do something..." + shell: bash + run: | + MESSAGE=$(codex exec "請你進行自我介紹" 2>/dev/null) + { + echo "message<> "$GITHUB_OUTPUT" test: name: 2. TEST runs-on: ubuntu From 480ae5c83c82608dba6604a6de3397f71ba6a2ab Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 1 Jul 2026 15:20:21 +0800 Subject: [PATCH 5/9] =?UTF-8?q?chore(ci):=20Build=20=E6=AD=A5=E9=A9=9F?= =?UTF-8?q?=E5=82=B3=E5=85=A5=20CODEX=5FOAUTH=20secret=20=E4=BE=9B=20codex?= =?UTF-8?q?=20=E7=99=BB=E5=85=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 02ac9ef..49c6f93 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -15,6 +15,8 @@ jobs: uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }} - name: Build uses: ./ + with: + oauth: ${{ secrets.CODEX_OAUTH }} - name: Execute id: execute shell: bash From 2c8fdaf54fac7099da5005f0a38852ae742e4279 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 1 Jul 2026 16:38:01 +0800 Subject: [PATCH 6/9] =?UTF-8?q?chore(ci):=20Execute=20=E9=9A=8E=E6=AE=B5?= =?UTF-8?q?=E5=85=88=E8=BC=B8=E5=87=BA=20codex=20=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E8=99=9F=E5=86=8D=E5=9F=B7=E8=A1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 49c6f93..0cbad8d 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -21,6 +21,7 @@ jobs: id: execute shell: bash run: | + codex --version MESSAGE=$(codex exec "請你進行自我介紹" 2>/dev/null) { echo "message< Date: Wed, 1 Jul 2026 16:40:45 +0800 Subject: [PATCH 7/9] =?UTF-8?q?fix(ci):=20Execute=20=E9=9A=8E=E6=AE=B5?= =?UTF-8?q?=E5=B0=87=20codex=20=E5=AE=89=E8=A3=9D=E8=B7=AF=E5=BE=91?= =?UTF-8?q?=E5=8A=A0=E5=85=A5=20PATH=20=E4=BF=AE=E6=AD=A3=20command=20not?= =?UTF-8?q?=20found?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 0cbad8d..862494f 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -21,6 +21,7 @@ jobs: id: execute shell: bash run: | + export PATH="$HOME/.local/bin:$PATH" codex --version MESSAGE=$(codex exec "請你進行自我介紹" 2>/dev/null) { From 1d5d5d8a67b320cd0b63c2990bef17efb9e5449e Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 1 Jul 2026 16:45:13 +0800 Subject: [PATCH 8/9] =?UTF-8?q?fix(setup-codex):=20=E5=B0=87=20codex=20PAT?= =?UTF-8?q?H=20=E8=A8=AD=E5=AE=9A=E7=A7=BB=E8=87=B3=20action=20=E4=BB=A5?= =?UTF-8?q?=20GITHUB=5FPATH=20=E4=BE=9B=E5=BE=8C=E7=BA=8C=E6=AD=A5?= =?UTF-8?q?=E9=A9=9F=E4=BD=BF=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 1 - action.yml | 4 +++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 862494f..0cbad8d 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -21,7 +21,6 @@ jobs: id: execute shell: bash run: | - export PATH="$HOME/.local/bin:$PATH" codex --version MESSAGE=$(codex exec "請你進行自我介紹" 2>/dev/null) { diff --git a/action.yml b/action.yml index d4c2888..db9f8cf 100644 --- a/action.yml +++ b/action.yml @@ -15,7 +15,9 @@ runs: - name: Setup Codex env: CODEX_NON_INTERACTIVE: 1 - run: curl -fsSL https://chatgpt.com/codex/install.sh | sh + run: | + curl -fsSL https://chatgpt.com/codex/install.sh | sh + echo "$HOME/.local/bin" >> "$GITHUB_PATH" shell: bash - name: Login Codex with OAuth env: From 0d27faf9164011dfd8e2c7f060d8781af6d7cf29 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 1 Jul 2026 16:47:09 +0800 Subject: [PATCH 9/9] =?UTF-8?q?chore(ci):=20Execute=20=E9=9A=8E=E6=AE=B5?= =?UTF-8?q?=E7=A7=BB=E9=99=A4=20codex=20=E7=89=88=E6=9C=AC=E8=99=9F?= =?UTF-8?q?=E8=BC=B8=E5=87=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 0cbad8d..49c6f93 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -21,7 +21,6 @@ jobs: id: execute shell: bash run: | - codex --version MESSAGE=$(codex exec "請你進行自我介紹" 2>/dev/null) { echo "message<