一、服務(wù)與鉤子

• GitHub 倉(cāng)庫管理中的鉤子與服務(wù)區(qū)塊是 GitHub 與外部系統(tǒng)交互最簡(jiǎn)單的方式。

① 服務(wù)

• 首先來看一下服務(wù)，鉤子與服務(wù)整合都可以在倉(cāng)庫的設(shè)置區(qū)塊中找到，就在我們之前添加協(xié)作者與改變項(xiàng)目的默認(rèn)分支的地方。在 “Webhooks and Services” 標(biāo)簽下，會(huì)看到與服務(wù)與鉤子配置區(qū)域類似的內(nèi)容：

• 有許多可以選擇的服務(wù)，大多數(shù)是整合到其他的商業(yè)與開源系統(tǒng)中。它們中的大多數(shù)是為了整合持續(xù)集成服務(wù)、BUG 與問題追蹤系統(tǒng)、聊天室系統(tǒng)與文檔系統(tǒng)。通過設(shè)置一個(gè)非常簡(jiǎn)單的例子來介紹，如果從 “Add Service” 選擇 “email”，會(huì)得到一個(gè)類似“電子郵件服務(wù)配置”的配置屏幕：

• 在本例中，如果我們點(diǎn)擊 “Add service” 按鈕，每次有人推送內(nèi)容到倉(cāng)庫時(shí)，指定的電子郵件地址都會(huì)收到一封郵件。服務(wù)可以監(jiān)聽許多不同類型的事件，但是大多數(shù)只監(jiān)聽推送事件然后使用那些數(shù)據(jù)做一些事情。
• 如果有一個(gè)正在使用的系統(tǒng)想要整合到 GitHub，應(yīng)當(dāng)先檢查這里看有沒有已有的可用的服務(wù)整合。例如，如果正使用 Jenkins 來測(cè)試代碼庫，當(dāng)每次有人推送到倉(cāng)庫時(shí)可以啟用 Jenkins 內(nèi)置的整合啟動(dòng)測(cè)試運(yùn)行。

② 鉤子

• 如果需要做一些更具體的事，或者想要整合一個(gè)不在這個(gè)列表中的服務(wù)或站點(diǎn)，可以轉(zhuǎn)而使用更通用的鉤子系統(tǒng)。GitHub 倉(cāng)庫鉤子是非常簡(jiǎn)單的，指定一個(gè) URL 然后 GitHub 在任一期望的事件發(fā)生時(shí)就會(huì)發(fā)送一個(gè) HTTP 請(qǐng)求到那個(gè) URL。通常做這件事的方式是可以設(shè)置一個(gè)小的 web 服務(wù)來監(jiān)聽 GitHub 鉤子請(qǐng)求然后使用收到的數(shù)據(jù)做一些事情。
• 為了啟用一個(gè)鉤子，點(diǎn)擊上文中的“服務(wù)與鉤子配置區(qū)域”中的 “Add webhook” 按鈕，這會(huì)引導(dǎo)至一個(gè)類似“Web 鉤子配置”的頁面：

• Web 鉤子的設(shè)置非常簡(jiǎn)單，大多數(shù)情況下只需要輸入一個(gè) URL 與一個(gè)密鑰然后點(diǎn)擊 “Add webhook”，有幾個(gè)選項(xiàng)可以指定在哪個(gè)事件時(shí)想要 GitHub 發(fā)送請(qǐng)求，默認(rèn)的行為是只有當(dāng)某人推送新代碼到倉(cāng)庫的任一分支時(shí)的 push 事件獲得一個(gè)請(qǐng)求。
• 來看一個(gè)設(shè)置處理 web 鉤子的 web 服務(wù)的小例子，將會(huì)使用 Ruby web 框架 Sinatra，因?yàn)樗喈?dāng)簡(jiǎn)潔，應(yīng)該能夠輕松地看到我們正在做什么。假設(shè)我們想要在某個(gè)特定的人推送到我們的項(xiàng)目的特定分支并修改一個(gè)特定文件時(shí)得到一封郵件，可以相當(dāng)容易地使用類似下面的代碼做到：

require 'sinatra' require 'json' require 'mail'post '/payload' dopush = JSON.parse(request.body.read) # parse the JSON# gather the data we're looking forpusher = push["pusher"]["name"]branch = push["ref"]# get a list of all the files touchedfiles = push["commits"].map do |commit|commit['added'] + commit['modified'] + commit['removed']endfiles = files.flatten.uniq# check for our criteriaif pusher == 'schacon' &&branch == 'ref/heads/special-branch' &&files.include?('special-file.txt')Mail.deliver dofrom 'tchacon@example.com'to 'tchacon@example.com'subject 'Scott Changed the File'body "ALARM"endend end

• 這里拿到一個(gè) GitHub 傳送給我們的 JSON 請(qǐng)求然后查找推送者，他們推送到了什么分支以及推送的所有提交都改動(dòng)了哪些文件，然后我們檢查它是否與我們的條件區(qū)配，如果匹配則發(fā)送一封郵件。
• 為了開發(fā)與測(cè)試類似這樣的東西，在設(shè)置鉤子的地方有一個(gè)漂亮的開發(fā)者控制臺(tái)，可以看到 GitHub 為那個(gè) webhook 的最后幾次請(qǐng)求。對(duì)每一個(gè)鉤子，當(dāng)它發(fā)送后都可以深入挖掘，檢測(cè)它是否是成功的與請(qǐng)求及回應(yīng)的消息頭與消息體，這使得測(cè)試與調(diào)試鉤子非常容易：

• 開發(fā)者控制臺(tái)的另一個(gè)很棒的功能是可以輕松地重新發(fā)送任何請(qǐng)求來測(cè)試服務(wù)。

二、GitHub API

• 服務(wù)與鉤子給我們提供了一種方式來接收關(guān)于在倉(cāng)庫中發(fā)生的事件的推送通知，但是如何獲取相關(guān)事件的詳情呢？ 如何自動(dòng)化一些諸如添加協(xié)作者或給問題加標(biāo)簽的事情呢？
• 這是 GitHub API 派上用場(chǎng)的地方，在自動(dòng)化流行的趨勢(shì)下，GitHub 提供了大量的 API 接口，可以進(jìn)行幾乎任何能在網(wǎng)站上進(jìn)行的操作。接下來將會(huì)學(xué)習(xí)如何授權(quán)與連接到 API，如何通過 API 在一個(gè)問題上評(píng)論與如何修改一個(gè) Pull Request 的狀態(tài)。

① 基本用途

• 可以做的最基本的事情是向一個(gè)不需要授權(quán)的接口上發(fā)送一個(gè)簡(jiǎn)單的 GET 請(qǐng)求，該接口可能是一個(gè)用戶或開源項(xiàng)目的只讀信息。例如，如果我們想要知道更多關(guān)于名為 “schacon” 的用戶信息，可以運(yùn)行類似下面的東西：

$ curl https://api.github.com/users/schacon {"login": "schacon","id": 70,"avatar_url": "https://avatars.githubusercontent.com/u/70", # …"name": "Scott Chacon","company": "GitHub","following": 19,"created_at": "2008-01-27T17:19:28Z","updated_at": "2014-06-10T02:37:23Z" }

• 有大量類似這樣的接口來獲得關(guān)于組織、項(xiàng)目、問題、提交的信息?—?差不多就是能在 GitHub 上看到的所有東西，甚至可以使用 API 來渲染任意 Markdown 或?qū)ふ乙粋€(gè) .gitignore 模板：

$ curl https://api.github.com/gitignore/templates/Java {"name": "Java","source": "*.class# Mobile Tools for Java (J2ME) .mtj.tmp/# Package Files # *.jar *.war *.ear# virtual machine crash logs, see https://www.java.com/en/download/help/error_hotspot.xml hs_err_pid* " }

② 在一個(gè)問題上評(píng)論

• 然而，如果想要在網(wǎng)站上進(jìn)行一個(gè)操作，如在 Issue 或 Pull Request 上評(píng)論，或者想要查看私有內(nèi)容或與其交互，需要授權(quán)。這里提供了幾種授權(quán)方式，可以使用僅需用戶名與密碼的基本授權(quán)，但是通常更好的主意是使用一個(gè)個(gè)人訪問令牌，可以從設(shè)置頁的 “Applications” 標(biāo)簽生成訪問令牌：

• 它會(huì)詢問這個(gè)令牌的作用域與一個(gè)描述，確保使用一個(gè)好的描述信息，這樣當(dāng)腳本或應(yīng)用不再使用時(shí)會(huì)很放心地移除。
• GitHub 只會(huì)顯示令牌一次，所以記得一定要拷貝它，現(xiàn)在可以在腳本中使用它代替使用用戶名寫密碼來授權(quán)。 這很漂亮，因?yàn)榭梢韵拗葡胍龅姆秶⑶伊钆剖强蓮U除的。這也會(huì)有一個(gè)提高頻率上限的附加優(yōu)點(diǎn)，如果沒有授權(quán)的話，會(huì)被限制在一小時(shí)最多發(fā)起 60 次請(qǐng)求，如果授權(quán)則可以一小時(shí)最多發(fā)起 5000 次請(qǐng)求。
• 所以利用它來對(duì)我們的其中一個(gè)問題進(jìn)行評(píng)論，想要對(duì)一個(gè)特定問題 Issue #6 留下一條評(píng)論，必須使用剛剛生成的令牌作為 Authorization 頭信息，發(fā)送一個(gè)到 repos///issues//comments 的 HTTP POST 請(qǐng)求：

$ curl -H "Content-Type: application/json" \-H "Authorization: token TOKEN" \--data '{"body":"A new comment, :+1:"}' \https://api.github.com/repos/schacon/blink/issues/6/comments {"id": 58322100,"html_url": "https://github.com/schacon/blink/issues/6#issuecomment-58322100",..."user": {"login": "tonychacon","id": 7874698,"avatar_url": "https://avatars.githubusercontent.com/u/7874698?v=2","type": "User",},"created_at": "2014-10-08T07:48:19Z","updated_at": "2014-10-08T07:48:19Z","body": "A new comment, :+1:" }

• 現(xiàn)在如果進(jìn)入到那個(gè)問題，可以看到我們剛剛發(fā)布的評(píng)論，像如下所示的“從 GitHub API 發(fā)布的一條評(píng)論”一樣：

• 可以使用 API 去做任何可以在網(wǎng)站上做的事情?—?創(chuàng)建與設(shè)置里程碑、指派人員到 Issues 與 Pull Requests，創(chuàng)建與修改標(biāo)簽、訪問提交數(shù)據(jù)、創(chuàng)建新的提交與分支、打開關(guān)閉或合并 Pull Requests、創(chuàng)建與編輯團(tuán)隊(duì)、在 Pull Request 中評(píng)論某行代碼、搜索網(wǎng)站等等。

三、修改 Pull Request 的狀態(tài)

• 最后一個(gè)例子在使用拉取請(qǐng)求時(shí)非常有用，每一個(gè)提交可以有一個(gè)或多個(gè)與它關(guān)聯(lián)的狀態(tài)，有 API 來添加與查詢狀態(tài)。大多數(shù)持續(xù)集成與測(cè)試服務(wù)通過測(cè)試推送的代碼后使用這個(gè) API 來回應(yīng)，然后報(bào)告提交是否通過了全部測(cè)試，也可以使用該接口來檢查提交信息是否經(jīng)過合適的格式化、提交者是否遵循了所有貢獻(xiàn)準(zhǔn)則、提交是否經(jīng)過有效的簽名?—?種種這類事情。
• 假設(shè)在倉(cāng)庫中設(shè)置了一個(gè) web 鉤子訪問一個(gè)用來檢查提交信息中的 Signed-off-by 字符串的小的 web 服務(wù)：

require 'httparty' require 'sinatra' require 'json'post '/payload' dopush = JSON.parse(request.body.read) # parse the JSONrepo_name = push['repository']['full_name']# look through each commit messagepush["commits"].each do |commit|# look for a Signed-off-by stringif /Signed-off-by/.match commit['message']state = 'success'description = 'Successfully signed off!'elsestate = 'failure'description = 'No signoff found.'end# post status to GitHubsha = commit["id"]status_url = "https://api.github.com/repos/#{repo_name}/statuses/#{sha}"status = {"state" => state,"description" => description,"target_url" => "http://example.com/how-to-signoff","context" => "validate/signoff"}HTTParty.post(status_url,:body => status.to_json,:headers => {'Content-Type' => 'application/json','User-Agent' => 'tonychacon/signoff','Authorization' => "token #{ENV['TOKEN']}" })end end

• 希望這相當(dāng)容易做，在這個(gè) web 鉤子處理器中我們?yōu)g覽剛剛推送上來的每一個(gè)提交，在提交信息中查找字符串 Signed-off-by 并且最終使用 HTTP 向 /repos///statuses/<commit_sha> API 接口發(fā)送一個(gè)帶有狀態(tài)的 POST 請(qǐng)求。
• 在本例中可以發(fā)送一個(gè)狀態(tài)（success, failure, error）、一個(gè)發(fā)生了什么的描述信息、 一個(gè)用戶可以了解更多信息的目標(biāo) URL 與一個(gè) “context” 以防一個(gè)單獨(dú)的提交有多個(gè)狀態(tài)。例如，一個(gè)測(cè)試服務(wù)可以提供一個(gè)狀態(tài)與一個(gè)類似這樣的驗(yàn)證服務(wù)也可能提供一個(gè)狀態(tài)?—?“context” 字段是用來區(qū)別它們的。
• 如果某人在 GitHub 中打開了一個(gè)新的拉取請(qǐng)求并且這個(gè)鉤子已經(jīng)設(shè)置，會(huì)看到類似如下所示的“通過 API 的提交狀態(tài)”的信息：

• 現(xiàn)在可以看到一個(gè)小的綠色對(duì)勾標(biāo)記在提交信息中有 “Signed-off-by” 的提交旁邊，紅色的對(duì)勾標(biāo)記在作者忘記簽名的提交旁邊，也可以看到 Pull Request 顯示在那個(gè)分支上的最后提交的狀態(tài)，如果失敗的話會(huì)警告我們。如果對(duì)測(cè)試結(jié)果使用這個(gè) API 那么就不會(huì)不小心合并某些未通過測(cè)試的最新提交。

四、Octokit

• 盡管在這些例子中都是通過 curl 與基本的 HTTP 請(qǐng)求來做幾乎所有的事情，還有一些以更自然的方式利用 API 的開源庫存在著，被支持的語言包括 Go、Objective-C、Ruby 與 .NET，更多信息請(qǐng)?jiān)L問：Octokit。
• 關(guān)于全部 API 的完整文檔與常見任務(wù)的指南，請(qǐng)查閱：Github Docs。

與50位技術(shù)專家面對(duì)面20年技術(shù)見證，附贈(zèng)技術(shù)全景圖

總結(jié)

以上是生活随笔為你收集整理的GitHub之深入解析脚本·自定义与修改GitHub来更好地为特定的工作流程工作的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。