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

做者：王冬輝