介绍新的 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 编程夏令营 :)