GitHub Actions 管理 API 指南 (v1.2)

GIIP 平台提供用於管理和監控 GitHub 倉庫工作流 (Workflow) 執行歷史記錄的 API。

🔌 前往 GitHub 整合功能頁 →

📋 概述

GitHub Actions 管理 API 用於同步已註冊倉庫的最新工作流狀態，並提供相關數據，以便在發生故障時透過 GIIP 控制台立即查看。

🔐 認證與安全

• 標頭 (Header): 必須包含通用的 x-giip-ak / x-giip-sk 標頭。
• 令牌 (Token): githubToken 必須使用 GitHub Personal Access Token (Classic 或 Fine-grained)。

📡 API 詳情 (Sk3)

1. 查詢 GitHub 配置清單 (GitHubConfigsList)

• 命令: text=GitHubConfigsList
• jsondata: {"csn": 123} (可選)
• 說明: 返回按項目分類的 GitHub 聯動配置資訊。

2. 創建 GitHub 配置 (GitHubConfigCreate)

• 命令: text=GitHubConfigCreate
• jsondata:

{
  "csn": 123,
  "configName": "Backend Repo",
  "repoOwner": "org-name-or-user",
  "repoName": "repo-name",
  "githubToken": "ghp_..."
}

3. 工作流執行歷史查詢 (GitHubWorkflowRunsList)

• 命令: text=GitHubWorkflowRunsList
• jsondata: {"gcId": 123, "perPage": 20, "status": "all"}
• 說明: 查詢特定聯動配置 (gcId) 的 GitHub Actions 執行歷史。

🛡️ 巧用 Sk3 (高性能日誌)

在創建包含 GitHub Personal Access Token 等敏感資訊的配置或執行工作流同步操作時，建議使用 giipApiSk3 端點。

• 端點: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 安全優勢: 自動記錄任何嘗試洩露 githubToken 或異常調用的模式；並在發生錯誤時提供詳細的上下文 (Stacktrace)，以便迅速應對。
• 使用技巧: 利用 text 命令和 jsondata 的參數替換功能，在代碼層面安全地管理工作流查詢條件（如 perPage、status 等）。

疑難排解

症狀	原因	解決
返回 401 認證錯誤	缺少通用的 x-giip-ak / x-giip-sk 標頭	確認已包含兩個認證標頭。
工作流執行歷史為空	gcId 缺失/錯誤或 githubToken 權限不足	指定有效的 gcId，並為 PAT 授予 Actions/repo 讀取權限。
GitHubConfigCreate 失敗	repoOwner/repoName 拼寫錯誤或 githubToken 過期/無效	核對倉庫資訊及有效的 PAT (Classic/Fine-grained)。
RstVal 錯誤或 jsondata 解析失敗	jsondata 的 JSON 轉義/編碼錯誤	將 jsondata 作為有效 JSON 發送，並查閱 API 結果代碼指南。

---

版本: 1.3 最後更新: 2026-04-11 源碼: giipv3/public/help/api-github.zh-TW.md

---

相關文檔:

• API 結果代碼指南 (RstVal)