建置 GitHub Enterprise Server 存放庫

  • 發行項

Azure DevOps Services

您可以將內部部署 GitHub Enterprise Server 與 Azure Pipelines 整合。 您的內部部署伺服器可能會公開至因特網，或可能不是。

如果您的 GitHub Enterprise Server 可從執行 Azure Pipelines 服務的伺服器連線，則：

  • 您可以設定傳統組建和 YAML 管線
  • 您可以設定 CI、PR 和排程觸發程式

如果您的 GitHub Enterprise Server 無法從執行 Azure Pipelines 服務的伺服器連線，則：

  • 您只能設定傳統組建管線
  • 您只能啟動手動或排程的組建
  • 您無法設定 YAML 管線
  • 您無法為傳統組建管線設定 CI 或 PR 觸發程式

如果您的內部部署伺服器可從 Microsoft 裝載的代理程式連線，您可以使用它們來執行管線。 否則，您必須設定可存取內部部署伺服器的自我裝載代理程式，並擷取程序代碼。

可從 Azure Pipelines 連線

檢查的第一件事是是否可以從 Azure Pipelines 服務連線到您的 GitHub Enterprise Server。

  1. 在您的 Azure DevOps UI 中，流覽至您的項目設定，然後選取 [管線] 底下的 [服務 連線]。
  2. 選取 [ 新增服務連線 ]，然後選擇 [GitHub Enterprise Server ] 作為連線類型。
  3. 輸入必要的資訊，以建立 GitHub Enterprise Server 的連線。
  4. 在服務連線面板中選取 [ 驗證 ]。

如果驗證通過，則執行 Azure Pipelines 服務的伺服器就能夠連線到您的內部部署 GitHub Enterprise Server。 您可以繼續並設定連線。 然後，您可以在建立傳統組建或 YAML 管線時使用此服務連線。 您也可以設定管線的 CI 和 PR 觸發程式。 與 GitHub 搭配運作的 Azure Pipelines 中，大部分功能也適用於 GitHub Enterprise Server。 請檢閱 GitHub 的檔以了解這些功能。 以下是一些差異：

  • GitHub 與 Azure Pipelines 之間的整合可透過 GitHub Marketplace 中的 Azure Pipelines 應用程式更容易。 此應用程式可讓您設定整合，而不需要依賴特定使用者的 OAuth 令牌。 我們沒有與 GitHub Enterprise Server 搭配運作的類似應用程式。 因此，您必須使用 PAT、使用者名稱和密碼，或 OAuth 來設定 Azure Pipelines 與 GitHub Enterprise 伺服器之間的連線。
  • Azure Pipelines 支持數個 GitHub 安全性功能，以驗證來自外部分支的貢獻。 例如，儲存在管線中的秘密無法提供給執行中的作業使用。 使用 GitHub Enterprise 伺服器時，無法使用這些保護。
  • GitHub Enterprise 伺服器無法使用批注觸發程式。 您無法在 GitHub Enterprise 伺服器存放庫提取要求中使用批注來觸發管線。
  • GitHub Enterprise 伺服器不提供 GitHub Checks。 所有狀態更新都是透過基本狀態。

無法從 Azure Pipelines 連線

如上一節所述，驗證 GitHub Enterprise Server 連線失敗時，Azure Pipelines 無法與伺服器通訊。 這可能是您的企業網路設定方式所造成。 例如，您網路中防火牆可能會防止外部流量連線到您的伺服器。 在此情況下，您有兩個選項：

  • 請與您的 IT 部門合作，在 Azure Pipelines 與 GitHub Enterprise Server 之間開啟網路路徑。 例如，您可以將例外狀況新增至防火牆規則，以允許來自 Azure Pipelines 的流量流經。 請參閱 Azure DevOps IP 上的一節，以查看您需要允許的 IP 位址。 此外，您需要有 GitHub Enterprise Server 的公用 DNS 專案，Azure Pipelines 可以將伺服器的 FQDN 解析為 IP 位址。 在所有這些變更中，嘗試在 Azure Pipelines 中建立並驗證 GitHub Enterprise Server 連線。

  • 您可以使用其他 Git 連線，而不是使用 GitHub Enterprise Server 連線。 請務必取消核取 [嘗試從 Azure Pipelines 存取此 Git 伺服器] 的選項。 使用此連線類型時，您只能設定傳統組建管線。 CI 和 PR 觸發程式無法在此設定中運作。 您只能啟動手動或排程的管線執行。

可從 Microsoft 裝載的代理程式連線

您可能必須做出的另一個決定是使用 Microsoft 裝載的代理程式或自我裝載代理程式來執行管線。 這通常歸結於 Microsoft 裝載的代理程式是否可以連線到您的伺服器。 若要檢查是否可以，請建立簡單的管線以使用 Microsoft 裝載的代理程式，並務必新增步驟以從您的伺服器簽出原始程式碼。 如果通過，您可以繼續使用 Microsoft 裝載的代理程式。

無法從 Microsoft 裝載的代理程式連線

如果上一節所述的簡單測試管線失敗，並出現錯誤 TF401019: The Git repository with name or identifier <your repo name> does not exist or you do not have permissions for the operation you are attempting，則無法從 Microsoft 裝載的代理程式連線到 GitHub Enterprise Server。 這再次可能是因為防火牆封鎖來自這些伺服器的流量所造成。 在此情況下，您有兩個選項：

  • 請與您的 IT 部門合作，在 Microsoft 裝載的代理程式和 GitHub Enterprise Server 之間開啟網路路徑。 請參閱 Microsoft 裝載代理程式中的網路功能一節。

  • 切換至使用 自我裝載代理 程式或 擴展集代理程式。 您可以在網路內設定這些代理程式，因此可以存取 GitHub Enterprise Server。 這些代理程式只需要對 Azure Pipelines 進行輸出連線。 不需要開啟輸入連線的防火牆。 請確定您在建立 GitHub Enterprise Server 連線時所指定的伺服器名稱可從自我裝載的代理程式解析。

Azure DevOps IP 位址

Azure Pipelines 會將要求傳送至 GitHub Enterprise Server 至：

  • 在管線建立期間查詢存放庫清單（傳統和 YAML 管線）
  • 在管線建立期間尋找現有的 YAML 檔案 （YAML 管線）
  • 簽入 YAML 檔案 （YAML 管線）
  • 在管線建立期間註冊 Webhook （傳統和 YAML 管線）
  • 呈現 YAML 檔案的編輯器（YAML 管線）
  • 在執行之前解析範本並展開 YAML 檔案 （YAML 管線）
  • 檢查上次排程執行之後是否有任何變更（傳統和 YAML 管線）
  • 擷取有關使用者介面中最新認可和顯示的詳細數據（傳統和 YAML 管線）

您可以觀察到 YAML 管線基本上需要 Azure Pipelines 與 GitHub Enterprise Server 之間的通訊。 因此，如果 Azure Pipelines 看不到 GitHub Enterprise Server，就無法設定 YAML 管線。

當您使用 其他 Git 連線來設定傳統管線時，請停用 Azure Pipelines 服務與 GitHub Enterprise Server 之間的通訊，並使用自我裝載的代理程式來建置程式代碼，您將獲得降級的體驗：

  • 您必須在管線建立期間手動輸入存放庫的名稱
  • 您無法使用 CI 或 PR 觸發程式，因為 Azure Pipelines 無法在 GitHub Enterprise Server 中註冊 Webhook
  • 您無法搭配選項使用排程的觸發程式，只有在有變更時才能建置
  • 您無法在使用者介面中檢視最新認可的相關信息

如果您想要設定 YAML 管線，或想要增強傳統管線的體驗，請務必啟用從 Azure Pipelines 到 GitHub Enterprise Server 的通訊。

若要允許來自 Azure DevOps 的流量連線到您的 GitHub Enterprise Server，請將輸入連線中指定的 IP 位址或服務標籤新增至防火牆的允許清單。 如果您使用 ExpressRoute，請務必將 ExpressRoute IP 範圍包含在防火牆的允許清單中。

限制

  • 為了獲得最佳效能，我們建議在單一存放庫中最多 50 個管線。 為了獲得可接受的效能，我們建議在單一存放庫中最多100個管線。 處理推送至存放庫所需的時間會隨著該存放庫中的管線數目而增加。 每當推送至存放庫時，Azure Pipelines 必須載入該存放庫中的所有 YAML 管線，以找出其中是否有任何管線需要執行，而且載入每個管線會產生效能損失。 除了效能問題之外，在單一存放庫中有太多管線可能會導致 GitHub 端的節流，因為 Azure Pipelines 可能會在短時間內提出太多要求。
  • 在管線中使用 延伸 和 包含 範本會影響 Azure Pipelines 提出 GitHub API 要求的速率，並可能導致 GitHub 端的節流。 在執行管線之前，Azure Pipelines 必須產生完整的 YAML 程式代碼，因此需要擷取所有範本檔案。
  • Azure Pipelines 最多會將 2000 個分支從存放庫載入 Azure Devops 入口網站中的下拉式清單，例如手動和排程組建設定的預設分支，或在手動執行管線時選擇分支時。 如果您沒有在清單中看到所需的分支，請手動輸入所需的分支名稱。

常見問題集

GitHub Enterprise 整合的相關問題分為下列類別：

失敗的觸發程式

我剛使用 CI/PR 觸發程式建立新的 YAML 管線，但不會觸發管線。

請遵循下列步驟來針對失敗的觸發程式進行疑難解答：

  • 您的 YAML CI 或 PR 觸發 程式是否由 UI 中的管線設定覆寫？ 編輯管線時，請選擇 ...，然後選擇 [觸發程式]。

    Pipeline settings UI.

    請從此處檢查 [覆寫 YAML 觸發程式] 設定，以取得存放庫可用的觸發程式類型（持續整合或提取要求驗證）。

    Override YAML trigger from here.

  • Webhook 可用來將更新從 GitHub Enterprise 傳達至 Azure Pipelines。 在 GitHub Enterprise 中，流覽至存放庫的設定，然後流覽至 Webhook。 確認 Webhook 存在。 通常您應該會看到兩個 Webhook - 推送，pull_request。 如果您未這麼做，則必須重新建立服務連線，並更新管線以使用新的服務連線。

  • 選取 GitHub Enterprise 中的每個 Webhook，並確認對應至使用者認可的承載存在，且已成功傳送至 Azure DevOps。 如果無法將事件傳達給 Azure DevOps，您可能會在這裡看到錯誤。

  • 當 Azure Pipelines 從 GitHub 收到通知時，會嘗試連絡 GitHub 並擷取存放庫和 YAML 檔案的詳細資訊。 如果 GitHub Enterprise Server 位於防火牆後方，此流量可能無法連線到您的伺服器。 請參閱 Azure DevOps IP 位址 ，並確認您已將例外狀況授與所有必要的 IP 位址。 這些IP位址可能已變更，因為您原本已設定例外狀況規則。

  • 管線已暫停或停用嗎？ 開啟管線的編輯器，然後選取要檢查 設定。 如果您的管線已暫停或停用，則觸發程式無法運作。

  • 您是否已在正確的分支中更新 YAML 檔案？ 如果您將更新推送至分支，則相同分支中的 YAML 檔案會控管 CI 行為。 如果您將更新推送至來源分支，則合併來源分支與目標分支所產生的 YAML 檔案會控管 PR 行為。 請確定正確分支中的 YAML 檔案具有必要的 CI 或 PR 組態。

  • 您是否已正確設定觸發程式？ 當您定義 YAML 觸發程式時，您可以同時指定分支、標記和路徑的 include 和 exclude 子句。 請確定 include 子句符合認可的詳細數據，而且 exclude 子句不會排除這些子句。 檢查觸發程式的語法，並確定其正確無誤。

  • 您是否在定義觸發程式或路徑時使用變數？ 不支援。

  • 您是否使用 YAML 檔案的樣本？ 如果是，請確定您的觸發程式定義於主要 YAML 檔案中。 不支援範本檔案內定義的觸發程式。

  • 您是否已排除您推送變更的分支或路徑？ 將變更推送至內含分支中的包含路徑，以進行測試。 請注意，觸發程式中的路徑會區分大小寫。 在指定觸發程式中的路徑時，請務必使用與實際資料夾相同的案例。

  • 您剛推送新分支嗎？ 如果是，新分支可能不會啟動新的執行。 請參閱一節。

我的 CI 或 PR 觸發程式正常運作。 但是，他們現在停止工作了。

首先，請流覽上一個問題中的疑難解答步驟，然後遵循下列其他步驟：

  • 您的PR中有合併衝突嗎？ 若為未觸發管線的PR，請開啟它並檢查是否有合併衝突。 解決合併衝突。

  • 您遇到推送或 PR 事件的處理延遲嗎？ 您通常會查看問題是否為單一管線的特定問題，或是您專案中所有管線或存放庫通用，來驗證延遲。 如果任何存放庫的推送或PR更新都表現出此徵兆，我們可能會遇到處理更新事件的延遲。 以下是延遲可能發生的一些原因：

    • 我們在狀態 頁面上遇到服務中斷。 如果狀態頁面顯示問題，則我們的小組必須已經開始處理。 請經常檢查頁面，以取得問題的更新。
    • 您的存放庫包含太多 YAML 管線。 為了獲得最佳效能，我們建議在單一存放庫中最多 50 個管線。 為了獲得可接受的效能，我們建議在單一存放庫中最多100個管線。 有的管線越多，推送至該存放庫的處理速度就越慢。 每當推送至存放庫時，Azure Pipelines 必須載入該存放庫中的所有 YAML 管線，以找出其中是否有任何管線需要執行，而且每個新管線都會產生效能損失。
    • 您的 GitHub Enterprise Server 實例可能會布建不足，以減緩處理來自 Azure Pipelines 的要求。 深入瞭解 GitHub Enterprise Server 的硬體考慮 。

簽出失敗

您是否使用 Microsoft 裝載的代理程式？ 若是如此，這些代理程式可能無法連線到您的 GitHub Enterprise Server。 如需詳細資訊，請參閱 無法從 Microsoft 裝載的 代理程式連線。

錯誤的版本

管線中使用了錯誤的 YAML 檔案版本。 這是為什麼？

  • 針對 CI 觸發程式，系統會評估您要推送之分支中的 YAML 檔案，以查看是否應該執行 CI 組建。
  • 針對PR觸發程式，會評估合併PR來源和目標分支所產生的YAML檔案，以查看是否應該執行PR組建。