在工具鏈中將 GitHub 設定為來源儲存庫
Continuous Delivery 將於 2027 年 2 月 12 日在以下地區停止服務:au-syd、ca-tor、us-east。 Code Risk Analyzer 也將於該日於所有地區停止服務。 若某個區域未實際使用這些功能,該區域中的功能可能會提前停用,並停止接受新的實例。 了解更多
在您的 IBM Cloud 工具鏈中設定 GitHub,以便管理原始碼、透過拉取請求進行協作,並在程式碼變更時觸發建置管線執行。
GitHub Enterprise 是 Git 儲存庫的內部部署 Web 型管理服務。
GitHub Issues 是一項追蹤工具,可將您的工作和方案都保留在一個位置。 它與您的開發儲存庫整合,因此您可以專注於重要作業。
您可以將 GitHub 配置為工具鏈中的工具整合,以在 GitHub.com 或公司 GitHub Enterprise 實例的新或現有儲存庫中管理原始碼。 透過 Wiki、問題追蹤及取回要求來參與社交編碼。
如果您要在建立工具鏈時配置此工具整合,請遵循下列步驟:
-
如果您是將原始碼儲存至 GitHub 儲存庫,請按一下「可配置的整合」區段中的 GitHub。 IBM Cloud GitHub 若您正在 IBM Cloud Public 上設定此工具整合,必須透過選擇 OAuth、「個人存取憑證」或「GitHub 應用程式」來授權 存取。
-
如果您選擇 OAuth,請按一下授權進入 GitHub 網站。 如果您沒有作用中的 GitHub 階段作業,則系統會提示您登入。 按一下授權應用程式,以容許 IBM Cloud 存取 GitHub 帳戶。 如果您有作用中的 GitHub 階段作業,但最近未輸入過密碼,則系統可能會提示您輸入 GitHub 密碼進行確認。
-
如果您選擇「個人存取記號」,則必須輸入個人存取記號,以用來授權 GitHub 複製儲存庫並代表您執行其他動作。 如果您沒有個人存取記號,則可以遵循 GitHub 網站上的說明文件來建立個人存取記號。 確定您的個人存取記號具有
repo、delete_repo、read:user及workflow權限。 -
如果您選擇「GitHub」應用程式,IBM Cloud 會使用「GitHub」應用程式的安裝來代表您向 GitHub 進行驗證,而非使用 OAuth 令牌。 GitHub 應用程式提供更細緻的權限控制,且不依賴個別使用者的憑證。 請選擇下列其中一種方法:
-
受管 — 使用 IBM 提供的 GitHub 應用程式,該應用程式已針對您的 GitHub 伺服器預先設定好。 點擊「授權」,系統將將您導向 GitHub,,您可在該頁面批准該應用程式存取您的帳戶。
-
自訂 — 請自備「GitHub」應用程式。 請輸入 App ID 以及您已在儲存庫中註冊並安裝的 GitHub 應用程式的私密金鑰 (格式為 PEM )。 您必須將此應用程式安裝在任何您希望與此整合功能搭配使用的儲存庫上。 如需有關建立 GitHub 應用程式的更多資訊,請參閱 GitHub 文件。
-
-
-
若您正在自己的 GitHub Enterprise 伺服器上使用儲存庫,請在可配置的整合區段中,點選自訂伺服器。
a. 為您的自訂 GitHub 伺服器輸入標題,指定伺服 URL 器的根目錄,並輸入您的個人存取權杖。
b. 如果您沒有個人存取記號,則可以遵循 GitHub 網站上的說明文件來建立個人存取記號。
c. 如果您的GitHub伺服器是氣隙的或無法在公共互聯網上訪問,您可以連接並整合Delivery Pipeline Private Worker 以在您自己的Kubernetes基礎設施上運行,以訪問內部或本地資源。 有關Delivery Pipeline Private Workers 的更多信息,請參閱 使用Delivery Pipeline Private Workers。
d. 如果您的 GitHub Enterprise 伺服器已註冊 GitHub 應用程式,您也可以選擇「GitHub」應用程式驗證方式,並提供您的 App ID 和私密金鑰;或者,若您的伺服器已預先設定好託管應用程式,則可直接使用該應用程式。
-
檢閱 GitHub 儲存庫的預設目標儲存庫位置。 那些儲存庫是從範例儲存庫中複製而來。 必要的話,請變更目標儲存庫的名稱。
如果您有工具鏈,並且要新增此工具整合到其中,請遵循下列步驟:
-
從 IBM Cloud 控制台點擊選單圖示(
)> 平台自動化 > 工具鏈。 在工具鏈頁面中,點擊該工具鏈以開啟其概覽頁面。
-
點擊新增工具。
-
在「工具整合」區段中,按一下 GitHub。
-
按一下您要使用的 GitHub 伺服器。
-
如果您有 GitHub 或 GitHub Enterprise 儲存庫並且想要使用它,請針對儲存庫類型按一下現有,然後鍵入 URL。
-
如果您要使用新的 GitHub 或 GitHub Enterprise 儲存庫,請鍵入儲存庫的名稱,並鍵入您所複製或分出之儲存庫的 URL,然後選取儲存庫類型:
a. 若要建立空的儲存庫,請按一下新建。
b. 若要建立 GitHub 或 GitHub Enterprise 儲存庫的副本,請按一下複製。
c. 若要分出 GitHub 或 GitHub Enterprise 儲存庫,以透過取回要求來提出變更,請按一下分出。
-
如果您是具有升級帳戶的 GitHub.com 使用者,或者已選取 GitHub Enterprise 伺服器,並且希望在該伺服器上建立新的專用儲存庫,請選取使此儲存庫成為專用勾選框。
-
如果要使用 GitHub 的 Issues 進行問題追蹤,請選取啟用 GitHub Issues 勾選框。
-
若要透過建立確定的標籤和註解以及確定所參照之問題的標籤和註解來追蹤程式碼變更部署,請選取追蹤程式碼變更部署勾選框。
-
按一下建立整合。
-
從工具鏈的「概觀」頁面中,在 儲存庫 卡上,按一下您要使用的 GitHub 或 GitHub Enterprise 儲存庫。 根據您已選取的儲存庫,會開啟 GitHub 網站或公司的 GitHub Enterprise 儲存庫,您可以在其中檢視儲存庫的內容。
-
如果您已啟用 GitHub Issues,請按一下 GitHub Issues 將它開啟。 您可以將此 GitHub Issues 實例用於整個工具鏈,即使工具鏈包含多個 GitHub 或 GitHub Enterprise 儲存庫。
如果您沒有要鏈結之儲存庫的管理者專用權,則整合會受到限制,因為您無法使用 Webhook。 需要有 Webhook,才能在將確定推送至儲存庫時自動執行管線。 如果沒有 Webhook,您必須手動啟動管線。
使用 API 來配置 GitHub
工具 GitHub 整合支援下列配置參數,您可在 建立、讀取及 更新工具整合時,透過工具鏈 HTTP API 與 SDK 使用這些參數。
您必須在要求內文中以 githubconsolidated 值指定 tool_type_id 內容。
| 參數 | 用法 | 類型 | Terraform 引數 | 說明 |
|---|---|---|---|---|
| API 根路徑網址 | 選用,可更新 | 字串 | API 根路徑網址 | API 根目錄 URL 的 伺服器 GitHub。 |
| API 金鑰 | 選用,可更新 | 密碼 | API 金鑰 | 個人存取憑證 (PAT)。 只有在 auth_type 設為 pat 時,才需要此參數,否則會忽略它。 |
| AUTH_TYPE | 選用,可更新 | 字串 | AUTH_TYPE | 設定存取 Git 提供者時要使用的驗證方式。 有效值為 oauth、pat 以及 github_app。 當指定 github_app 時,驗證會使用 GitHub 應用程式安裝憑證,而非 OAuth 使用者憑證或 PAT。 |
| 自動初始化 | 可選、不可變更、Default: false |
布林 | 自動初始化 | 將此值設為 true,以使用 Readme 檔來起始設定此儲存庫。 只有在您建立儲存庫時,才會使用此參數。 |
| 盲接 | 可选、可更新、Default: false |
布林 | 盲接 | 將此值設為 true 表示伺服器無法在公用網際網路上定址。IBM Cloud 無法驗證您提供的連線詳細資料。 將停用需要 Git 伺服器的 API 存取權的特定功能。 Delivery Pipeline 只會使用具有 Git 伺服器網路存取權的專用工作者節點來運作。 |
| 預設分支 | 選用,可更新 | 字串 | 預設分支 | Git 儲存庫的預設分支。 |
| enable_traceability | 可选、可更新、Default: false |
布林 | enable_traceability | 將此值設定為,即可透過在提交、拉取請求及相關問題上建立標籤、標記和註解,true 來追蹤程式碼變更的部署狀況。 |
| git_id | 選用,不可變 | 字串 | git_id | 針對 github.com,將此值設為 github,或設為自訂 GitHub Enterprise 伺服器的 GUID。 |
| github_app_auth_method | 選用,可更新 | 字串 | github_app_auth_method | 當 auth_type 為 github_app 時,應使用「GitHub」應用程式的驗證方式。 請將此設定設為 managed,以使用 IBM 提供的 GitHub 應用程式(預設值);或設為 custom,透過 github_app_credential_app_id 和 github_app_credential_private_key 提供您自己的 GitHub 應用程式憑證。 |
| github_app_credential_app_id | 選用,可更新 | 字串 | github_app_credential_app_id | GitHub App ID 提供客製化的 GitHub 應用程式。 當 github_app_auth_method 為 custom`` 時,此參數為必填。 |
| github_app_credential_private_key | 選用,可更新 | 密碼 | github_app_credential_private_key | 用於自訂 GitHub 應用程式的 RSA 私鑰( PEM 格式)。 當 github_app_auth_method 為 custom`` 時,此參數為必填。 金鑰是以加密形式儲存的。 |
| has_issues | 可选、可更新、Default: true |
布林 | 工具鏈問題啟用狀態 | 將此值設為 true,以啟用 GitHub 儲存庫上的問題,並將 Issues 工具卡新增至工具鏈。 將值設為 false 可從工具鏈中移除工具整合卡。 此設定不會影響是否在 GitHub 儲存庫本身啟用問題。 |
| 整合負責人 | 選用,可更新 | 字串 | 整合負責人 | 選取執行 Git 作業的使用者身分。 |
| owner_id | 選用,不可變 | 字串 | owner_id | 擁有儲存庫的 GitHub 使用者或組織。 當您建立儲存庫或複製或分出儲存庫時,需要此參數。 當您鏈結至現有儲存庫時,會計算此值。 |
| 私人儲存庫 | 可選、不可變更、Default: false |
布林 | 私人儲存庫 | 將此值設為 true,以在您建立儲存庫或複製或分出儲存庫時將儲存庫設為專用。 當您鏈結至現有儲存庫時,不會使用此參數。 |
| repo_id | 選用,不可變 | 字串 | repo_id | GitHub 儲存庫的 ID。 |
| repo_name | 選用,不可變 | 字串 | repo_name | 要建立的 GitHub 儲存庫名稱。 當您建立儲存庫或複製或分出儲存庫時,需要此參數。 當您鏈結至現有儲存庫時,會計算此值。 |
| repo_url | 選用,不可變 | 字串 | repo_url | 此工具整合的存取 GitHub 權限 URL 設定。 鏈結至現有儲存庫時需要此參數。 當您建立儲存庫或複製或分出儲存庫時,會計算此值。 |
| 根網址 | 選用,可更新 | 字串 | 根網址 | 伺服 URL 器的根目錄。例如:https://github.example.com |
| 原始碼儲存庫網址 | 選用,不可變 | 字串 | 原始碼儲存庫網址 | 您正在分叉或複製的儲存 URL 庫的 當您建立子處理程序或複製儲存庫時,需要此參數。 當您建立儲存庫或鏈結至現有儲存庫時,不會使用它。 |
| title | 選用,可更新 | 字串 | title | 伺服器的標題。例如,我的 GitHub Enterprise 伺服器 |
| 代幣網址 | 選用,可更新 | 字串 | 代幣網址 | 用於向伺服器 GitHub 進行授權的 URL 憑證。 |
| 類型 | 必要,不可變 | 字串 | 類型 | 要執行以起始設定新工具整合的作業。 使用 new 來建立 Git 儲存庫,clone 將現有儲存庫複製到新的 Git 儲存庫,fork 以分出現有 Git 儲存庫,或者 link 以鏈結至現有 Git 儲存庫。 |
使用 GitHub App 驗證
GitHub 應用程式驗證是「OAuth」和「個人存取憑證 (PAT)」方法的替代方案。 GitHub 應用程式是以應用程式身分進行驗證,而非以使用者身分進行驗證,這能提供更細粒度的儲存庫權限、無需依賴個別使用者帳戶的憑證,且所產生的憑證會自動輪替,並限定於特定儲存庫的範圍內。
共有兩種模式可供選擇:
- 受管理 (
github_app_auth_method: managed) - IBM Cloud 使用由 IBM 提供的 GitHub 應用程式,該應用程式已針對您的 GitHub 伺服器預先註冊。 您透過 OAuth 的授權流程授權此應用程式,而由此產生的用戶至伺服器憑證(
ghu_)將被自動儲存並使用。 - 自訂 (
github_app_auth_method: custom) - 您可於 GitHub 或 GitHub Enterprise 上註冊並管理您自己的 GitHub 應用程式。 您需提供 App ID 以及採用 PEM 編碼的 RSA 私鑰。IBM Cloud 會利用這些憑證,自動鑄造有效期短暫的安裝存取憑證 (
ghs_)。 您必須在每個欲與此整合功能搭配使用的儲存庫上安裝 GitHub 應用程式。
在開始進行自訂 GitHub App 驗證之前
在設定自訂的「GitHub」應用程式驗證之前,請先完成以下步驟:
-
在您的 GitHub 組織或個人帳戶中 建立一個 GitHub 應用程式。 請至少授予該應用程式以下儲存庫權限:
- 內容:讀取與寫入
- 元資料:唯讀
- 拉取請求:讀取與寫入(若您使用拉取請求追蹤功能)
- 工作流程:讀取與寫入(若您的管線會觸發「GitHub」動作)
-
為該應用程式產生一個私密金鑰,並儲存 PEM 檔案。 在設定整合時,您將需要此金鑰。
-
請在您的工具鏈將存取的組織或儲存庫上安裝「GitHub」應用程式。 必須先安裝該應用程式,才能驗證憑證。
在您使用 App ID 及私密金鑰設定工具整合後,IBM Cloud 會透過呼叫 GitHub API 來驗證憑證。 如果指定儲存庫中尚未安裝該應用程式,系統會顯示錯誤訊息,提示您先安裝該應用程式。