Jenkins 插件开发之旅：两天内从 idea 到发布(下篇)

首发于 Jenkins 中文社区

本文分上下两篇，上篇介绍了从产生 idea 到插件开发完成的过程； 下篇将介绍将插件托管到 Jenkins 插件更新中心的一系列过程。

托管插件

托管插件包括一系列流程步骤。 笔者完成了它全部步骤（包括非必须的步骤），其中主要有两个具备标志性的任务：

• 插件代码被托管在 jenkinsci GitHub 组织的一个仓库，而后做者拥有它的管理权限。
  笔者插件的代码仓库为：jenkinsci/maven-snapshot-check-plugin 。
• 你能够将插件发布到 Jenkins 项目的 Maven 仓库，它是 Jenkins 项目所使用的更新站点的数据来源。

准备工做

在请求插件托管以前，须要完成如下几个步骤。

查找相似的插件

Jenkins 社区欢迎任何人的贡献，但为了让 Jenkins 用户受益，它要求查找解决相同或相似问题的插件，看看是否能够与现有的维护人员联手。能够在 plugins.jenkins.io 查看全部的插件，以确认是否已有相似的插件实现了你计划实现的功能。

笔者在以前已进行过查找，并无找到能够实现笔者计划实现的功能的相似插件。

命名规约

Jenkins 制定了一些与插件相关的命名规约。插件开发者要确保遵循这些命名规约。

artifactId

插件的 artifactId 被用于文件基本名称，是 Jenkins 插件和更新站点的惟一标识。
它须要遵循一些发布规约：

• 使用小写 ID ，并根据须要使用连字符分隔术语。
• 除非名称有任何意义，不然不要在 ID 中包含 jenkins 或 plugin 。

插件名称

插件的名称在 Jenkins UI 和其它地方（如：插件站点）展现给用户。
若是能够，建议使用简短的描述性名称，如 Subversion 。
笔者所写的插件的名称为：Maven SNAPSHOT Check 。

groupId

推荐使用 io.jenkins.plugins 或 org.jenkins-ci.plugins 做为 groupId 。 可是不由止其余组织 ID ，除非它们是恶意的（例如引用与你没有关系的组织）。 笔者所写的插件使用的 groupId 为: org.jenkins-ci.plugins 。

Java 源代码

Jenkins 项目通常遵循 Oracle Java 代码规约，可是并无很好的强制甚至在核心组件中。个别的插件维护者有时会选择使用不一样的风格指南做为插件。 笔者平常使用 IDEA 进行开发，以前安装了「阿里 Java 规约插件」， 于是使用它做为编码规约。

提交消息

Git 提交消息应该从引用与之相关的 JIRA 问题开始（若是适用）， 而后在第一行进行简短的总结，并在随后的行中提供更多详细信息。例如：

[JENKINS-00000] Frobnicate the widget
复制代码

若是给定的提交修复了指定的问题， 那么使用如下前缀中的任何一个将会自动化解决相关的 JIRA 问题。

[FIX JENKINS-00000] Frobnicate the widget
[FIXED JENKINS-00000] Frobnicate the widget
[FIXES JENKINS-00000] Frobnicate the widget
复制代码

因为还没过将插件托管，笔者并无遵循该规约，等插件发布后，笔者将考虑遵循该规约。

License

Jenkins 项目分发的全部插件都须要是免费的开源软件。 这适用于插件源代码及其全部依赖项。
要确保在 pom.xml 文件和仓库中的 LICENSE 文件指定协议。 官方建议使用 MIT license ，它用于 Jenkins 核心和大多数插件和库， 可是任何 OSI 批准的开源 license 均可以。 笔者这里使用了 MIT license 。

要求注册的帐号

经过 Jenkins 项目更新站点分发的插件须要托管在 jenkinsci GitHub 组织中，所以须要在 GitHub 上有一个帐号，而且须要有一个公共仓库来存放插件源代码。

为了完整地发布你的插件，须要注册一个 Jenkins 社区账号， 它可让你访问 JIRA，wiki 和 Maven 仓库 。

发起托管请求

注意：Jenkins 官方自动化流程使用更容易实现的 fork + 删除的方式（见下文），而不是转移仓库全部者。

登陆到 JIRA 而后在 HOSTING 项目建立一个问题。 请确保按照描述填写全部字段。Jenkins 项目成员将在几天内审查你的请求。若是审查人员要求你更改，那么请按照要求进行更改。

笔者提交的申请为：HOSTING-750， 比较幸运的是当天凌晨（北京时间）笔者的请求就被审查， 正巧那时笔者未眠，因而随后按要求进行了更改并在不久后该申请被审批经过。

一旦知足了全部的需求，你的仓库将被 fork 到 jenkinsci 组织中，而且你将被邀请加入该组织，而且将为你在 JENKINS 项目中建立 JIRA 组件。

此时，将要求你删除 Jenkins 从中 fork 的仓库。以后你能够经过再次从 jenkinsci 那里 fork 来从新建立它。这将确保 jenkinsci 仓库是 Github 上网络图的根。

这意味着：

• 不会混淆哪一个仓库是权威仓库。
• 即便在 GitHub 上没有大量的关注者，源代码搜索也会成功。
• 其余人更可能在 jenkinsci 仓库中提交 pull request（这是协做的理想选择）。

建立 wiki 页面

尽管这对发布插件来讲这不是严格要求的，但最好为插件建立一个 wiki 页面来存储文档。关于如何执行此操做的详细信息，请参阅插件 wiki 页面指南。

笔者所写的插件的 wiki 页面为：Maven SNAPSHOT Check Plugin 。 其间除了官方文档，笔者还参考了其它插件 wiki 页面的排版。

开启 CI 构建

Jenkins 项目托管了一个 Jenkins 实例来执行插件的持续集成构建。 官方推荐经过在插件的 Github 仓库根目录建立一个 Jenkinsfile，为在 Jenkinsci Github 组织中的插件设置 CI 构建。

典型的插件构建（ Maven 或 Gradle ）只需在 Jenkinsfile 中包含如下语句便可运行：

buildPlugin()
复制代码

申请上传权限

在源代码被 fork 到 jenkinsci 组织后，须要提交一个上传权限请求。 按照 jenkins-infra/repository-permissions-updater/ 仓库的 README 文件中所说的来作就能够。

Jenkins 项目在 Artifactory 上托管 Maven 制品，例如核心和插件发布。

它的权限系统与 Github 是独立的，限制了那些用户（由 Jenkins LDAP 账户标识，与 wiki 和 JIRA 同样）能够上传。 这个仓库包含 YAML 格式的 Artifactory 上传权限定义，以及将它们同步到 Artifactory 的工具。

先决条件：在申请权限以前，须要先用 Jenkins 社区账号登陆一次 Artifactory 。

要请求对制品（一般是插件）的上传权限，须要提交一个 PR ， 该 PR 须要建立与申请上传权限相关的 YAML 文件。 笔者所提交的 PR 为：Plugin: Permission for maven-snapshot-check-plugin 。

经过查看它能够看出该 PR 增长了一个文件：permissions/plugin-maven-snapshot-check.yml ，其内容以下：

name: "maven-snapshot-check"
github: "jenkinsci/maven-snapshot-check-plugin"
paths:
- "org/jenkins-ci/plugins/maven-snapshot-check"
developers:
- "donhui"
复制代码

在建立 PR 后，会有帮助说明以及 checklist 让提交人对该 PR 进行检查确认。
等这个 PR 被审批后，插件开发者就会拥有该插件的发布权限。

发布插件

前提

要先确认拥有发布该插件的权限。

Maven 要使用的 Artifactory 凭据

须要告诉 Maven 访问 Artifactory 的凭据。 登陆 Artifactory ，从用户 profile 中获取加密的密码。 在 ~/.m2/settings.xml 文件配置 server 认证信息，以下所示：

<settings xmlns="https://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

  <servers>
    <server>
      <id>maven.jenkins-ci.org</id> 
      <username>your_user_name_here</username>
      <password>your_encrypted_password_here</password>
    </server>
  </servers>

</settings>
复制代码

配置 GitHub 以接受你的 SSH key

当执行 release 时，Maven Release Plugin 会自动往仓库推送代码， 因此须要配置 GitHub 以接受你的 SSH key 。

更多信息能够参考：GitHub help on SSH 。

执行发布

当 GitHub 和 Maven 凭据配置好后，执行一次发布应该很简单，只须要运行下面的命令：

mvn release:prepare release:perform
复制代码

可能在执行发布时会遇到 "401 Unauthorized" 或 "403 Forbidden" 之类问题，这通常是 settings.xml 配置问题或是没有上传权限。一些公共的问题处理方案能够查看：HostingPlugins-Workingaroundcommonissues。

插件发布后，8 小时内，将能够在插件更新中心看到它。

笔者所写的 maven-snapshot-check 插件， 在插件列表页的地址为：plugins.jenkins.io/maven-snaps… 。

Jenkins 实例的插件管理页面的「可选插件」选项截图以下：

为插件分类

在 Jenkins 插件列表页面，能够对插件进行分类显示。

要为插件添加一个分类，须要向 jenkins-infra/update-center2 仓库提交一个 PR 。 笔者所提交的 PR 为：add maven-snapshot-check category 。

经过查看它能够看出该 PR 在 src/main/resources/label-definitions.properties 文件增长了一行，以下所示：

maven-snapshot-check=builder
复制代码

总结

两天的 Jenkins 插件开发之旅（尤为是 04.24 晚上花了不少时间）， 让笔者了解了插件开发的基本知识，并在托管插件的过程当中学到一些知识。 而后在周末花了几个小时总结回顾，并将它写成文档。 同时也但愿此文能给 Jenkins 插件开发者入门带来一点帮助！

参考

• Guide to Plugin Hosting
• Performing a Plugin Release

做者：王冬辉