介紹新的 GitLab 分支源插件

本文首發於：Jenkins 中文社區

原文連接    做者：baymac

譯者：Donghui Wang

介紹新的 GitLab 分支源插件

新的 GitLab 分支源插件，容許您基於 GitLab 用戶 或 組 或 子組 項目建立任務

GitLab 分支源插件已經走出 beta 階段，並已發佈到 Jenkins 更新中心。 它容許您基於 GitLab 用戶 或 組 或 子組 項目建立任務。 您能夠:

• 從 GitLab 用戶/組/子組導入單個項目的分支做爲任務（多分支流水線任務）
• 從 GitLab 用戶/組/子組導入全部或部分項目的分支做爲任務（GitLab 組任務或 GitLab 文件夾組織）

GitLab 組項目對項目進行掃描， 根據設置的規則導入流水線任務。 導入項目以後， Jenkins 當即基於 Jenkinsfile 流水線腳本運行任務而且將狀態通知到 GitLab 流水線狀態。 這個插件與其餘分支源插件不一樣，它提供了 GitLab 服務器配置，能夠在系統配置中配置。 Jenkins 配置即代碼 (JCasC) 也能夠用於配置服務器。 要想了解更多關於服務器配置的信息，請參考我以前的博客。

要求

• Jenkins - 2.176.2 (LTS)

• GitLab - v11.0+

建立任務

要建立多分支流水線任務（使用 GitLab 分支源）或 GitLab 組任務，您必須將 GitLab 我的訪問令牌添加到服務端配置。 憑據用於獲取項目的元數據，並在 GitLab 服務器上設置 hook。 若是令牌具備管理訪問權限，您還能夠設置 系統 Hook，而 Web Hook 能夠從任何用戶令牌設置。

建立多分支流水線任務

轉到 Jenkins > 新建任務 > 多分支流水線 > 添加源 > GitLab 項目

• Server - 從下拉菜單中選擇所需的 GitLab 服務器，須要在建立此任務以前進行配置。

• Checkout Credentials - 若是插件要構建任何私有項目，添加 SSHPrivateKey 或 用戶名/密碼 類型的憑據。若是全部的項目都是公開的則不須要檢出憑據。檢出憑據與 GitLab 服務器配置中的憑據(GitLab 我的訪問令牌 類型)不一樣。

• Owner - 能夠是 用戶、組 或 子組。 根據這一點填充 Projects 字段。

• Projects - 從下拉菜單中選擇要構建的項目。

• Behaviours - 這些特性是很是強大的工具，用於配置構建邏輯和構建後邏輯。咱們定義了新的特性。您能夠在倉庫文檔中看到全部信息。

保存並等待分支索引。您能夠從這裏自由導航，任務進度顯示在左側。

索引完成後，導入的項目將全部分支、合併請求和標籤列示爲任務。

查看每一個任務，您會發現左側有一些操做項:

• 您能夠經過選擇 當即構建 手動觸發任務。
• 您能夠經過選擇相應的按鈕訪問 GitLab 服務器上的特定分支/合併請求/標籤。

建立 GitLab 組類型任務

轉到 Jenkins > 新建任務 > GitLab Group

您能夠注意到，配置很是相似於多分支流水線任務，只是缺乏 Projects 字段。 您能夠添加在您的 Owner（用戶/組/子組）中全部項目。 表單驗證將與 GitLab 服務器檢查 owner 是否有效。 您能夠添加 Discover subgroup project 的特性，該特性容許您發現組或子組中全部子組的子項目，但此特性不適用於用戶。 在索引時，web hook 在每一個項目中建立。 GitLab Api 不支持建立組 web hook，因此這個插件不支持只有 GitLab EE 才支持的特性。

如今能夠查看導入的項目，若是須要，能夠在每一個文件夾上配置不一樣的設置。

GitLab 流水線狀態通知

GitLab 從任務排隊的角度獲得關於構建狀態的通知。

• 成功 - 任務成功了
• 失敗 - 任務失敗了而且合併請求還沒準備好合並
• 出錯 - 發生了意外；例如：Jenkins 任務被終止了
• 等待 - 任務正在構建隊列中等待

關於 GitLab 流水線狀態，有指向相應 Jenkins 任務構建的超連接。 要查看流水線階段和控制檯輸出，須要訪問 Jenkins 服務器。 咱們也計劃通知管道階段到 GitLab，但它有一些缺點，目前這已獲得解決，有將來的計劃添加它做爲特性。

您還能夠經過從特性列表中選擇 Skip pipeline status notifications 來跳過關於流水線狀態的 GitLab 通知。

合併請求

實現對項目合併請求的支持具備挑戰性。 第一，MR 有兩種類型，即原始分支和 Fork 的項目分支，所以每一個 head 必須有不一樣的實現。 第二，來自 fork 的 MR 可能來自不可信的源，因此實現了一種新的策略 Trust Members，它容許 CI 僅從具備 Developer/Maintainer/Owner 訪問級別的可信用戶構建 MR。

第三，來自 fork 的 MR 因爲 GitLab 的問題不支持流水線狀態通知，請參考這裏。 您能夠添加一個特性 Log Build Status as Comment on GitLab ，它容許那您添加一個 sudo 用戶（若是你但願 owner 用戶爲空）以在 commit/tag/mr 上對構建結果進行評論。 要添加 sudo 用戶，令牌必須具備管理訪問權限。 默認狀況下，只有失敗/出錯以評論的形式被記錄，可是您也能夠經過勾選複選框來啓用成功構建的日誌記錄。

有時候，合併請求由於外部錯誤而失敗，所以所以您但願經過評論 jenkins rebuild 來觸發 mr 的從新構建。 要啓用該觸發器，添加特性 Trigger build on merge request comment。 評論內容能夠在特性中修改。 出於安全緣由，評論者須要有該項目的 Developer/Maintainer/Owner 訪問權限。

Hook

若是在服務器配置中配置了 web hook，則在項目上自動建立 web hook。 請確保 web hook 經過 CSRF 過濾器。 Jenkins 監聽 /gitlab-webhook/post 路徑上的 web hook 。 GitLab 上 web hook 在如下事件上被觸發：

• Push Event - 當提交或分支被推送時

• Tag Event - 當新標籤被建立時

• Merge Request Event - 當合並請求被建立/更新

• Note Event - 當對合並請求進行評論時

若是令牌具備管理訪問權限，還能夠在 GitLab 服務器上設置系統 Hook。 在建立新項目時觸發系統 hook，Jenkins 根據配置觸發新項目的從新掃描，並在其上設置 web hook。 Jenkins 監聽 /gitlab-systemhook/post 路徑上你的系統 hook。 GitLab 上系統 hook 在 Repository Update Events 上被觸發：

你也可使用 Override Hook Management mode 特性來覆蓋默認你的 hook 管理以及選擇是否要使用不一樣的上下文（好比 Item）或徹底禁用它。

Job DSL 以及 JCasC

你可使用 Job DSL 來建立任務。 下面有一個 Job DSL 腳本的示例：

organizationFolder('GitLab Organization Folder') {
    description("GitLab org folder created with Job DSL")
    displayName('My Project')
    // "Projects"
    organizations {
        gitLabSCMNavigator {
            projectOwner("baymac")
            credentialsId("i<3GitLab")
            serverName("gitlab-3214")
            // "Traits" ("Behaviours" in the GUI) that are "declarative-compatible"
            traits {
                subGroupProjectDiscoveryTrait() // discover projects inside subgroups
                gitLabBranchDiscovery {
                    strategyId(3) // discover all branches
                }
                originMergeRequestDiscoveryTrait {
                    strategyId(1) // discover MRs and merge them with target branch
                }
                gitLabTagDiscovery() // discover tags
            }
        }
    }
    // "Traits" ("Behaviours" in the GUI) that are NOT "declarative-compatible"
    // For some 'traits, we need to configure this stuff by hand until JobDSL handles it // https://issues.jenkins.io/browse/JENKINS-45504 configure { def traits = it / navigators / 'io.jenkins.plugins.gitlabbranchsource.GitLabSCMNavigator' / traits traits << 'io.jenkins.plugins.gitlabbranchsource.ForkMergeRequestDiscoveryTrait' { strategyId(2) trust(class: 'io.jenkins.plugins.gitlabbranchsource.ForkMergeRequestDiscoveryTrait$TrustPermission') } } // "Project Recognizers" projectFactories { workflowMultiBranchProjectFactory { scriptPath 'Jenkinsfile' } } // "Orphaned Item Strategy" orphanedItemStrategy { discardOldItems { daysToKeep(10) numToKeep(5) } } // "Scan Organization Folder Triggers" : 1 day // We need to configure this stuff by hand because JobDSL only allow 'periodic(int min)' for now triggers { periodicFolderTrigger { interval('1d') } } } 複製代碼

你也可使用 JCasC 從 Job DSL 腳本直接建立任務。示例請查看該插件倉庫。

如何與咱們討論 bug 或新特性?

• 這個項目使用 Jenkins JIRA 來跟蹤問題。 你能夠查看 gitlab-branch-source-plugin 組件下面的問題。

• 在開發者郵件列表中發送你的郵件。

• 加入咱們的 Gitter channel。

將來的工做

• 積極維護 GitLab 分支源插件 並從用戶那裏獲取反饋以改進插件的用戶體驗。
• 擴展在 BlueOcean 中對 GitLab 流水線的支持。

資源

• GitLab API 插件
• GitLab API 插件 Wiki
• GitLab 分支源插件
• 項目概要
• GitHub 分支源插件發佈

感謝 Jenkins 以及 Google 編程夏令營 :)