Pygerrit with Gerrit REST API

Gerrit 是一套開放源始碼、以 Java 編寫而成的程式碼審查(Code Review)軟體，其功能性質類似於 GitHub，一樣以 Git 作為版本控制的基礎。Gerrit 同時提供了一系列的 API 讓使用者能夠方便讀取和更新資料，其以 REST 風格來做開發，因此稱為 Gerrit REST API。

Pygerrit 是一個用於與 Gerrit REST API 溝通的 Python 模組，其第一代由 Sony 開發，但目前看起來已經沒有在維護了，幸好有開發者推出了第二代 Pygerrit2，讓泰勞可以將很多例行性的工作自動化成 Python 腳本。本文範例所使用的都會是 Pygerrit2 喔！

架設 Gerrit Code Review

在開始測試之前，務必先架設好 Gerrit，最簡單的方式就是使用 Gerrit Docker Image，只需一行指令，上去建立一個 Repository 再把測試用的專案透過 Git 推送到 Gerrit 即可完成事前步驟。

$ docker run -ti -p 8080:8080 -p 29418:29418 gerritcodereview/gerrit
$ git push ssh://username@www.gerrit.com:29418/reponame HEAD:refs/heads/master

安裝 Pygerrit2

$ pip install pygerrit2 --user

撰寫 Python 腳本

先設定待會向 Gerrit 請求資訊時需要的認證。

auth = HTTPBasicAuth('username', 'password')
rest = GerritRestAPI(url='http://www.gerrit.com:8080', auth=auth)

若認證沒有問題，就可以開始嘗試請求資訊囉！第一個範例是將所有自己已 Submit 的 Change 列出來，回傳的資訊會是一個 List，稍微處理一下再打印出來。

changes = rest.get("/changes/?q=owner:self%20status:merged")
for change in changes:
    print("Change-Id:{}".format(change['change_id']))
    print("  Subject:{}".format(change['subject']))
    print("  Project:{}".format(change['project']))
    print("  Branch:{}".format(change['branch']))

下圖可以看到每個 Change 所對應到的 Change-Id、Subject、Project 和 Branch 名稱，當然這裡面還有很多資訊是泰勞沒有打印出來的。

Gerrit REST API 不僅僅能讀取資料，還可以實作很多遠端的操作，接下來會列出幾個泰勞曾經使用過的範例給大家參考。

Set Review

對 Gerrit 上的 Change 做 Code-Review 的動作(實際上 Reviewer 還是要認真 Review 程式碼才行喔！)。紅字 change 可以是 Change Number 或 Change-Id，不過不同分支上是可以擁有相同 Change-Id 的，這點需要注意一下。

def review(change):
        headers = {'content-disposition': 'attachment', 'content-type': 'application/json'}
        query = "/changes/" + str(change) + "/revisions/current/review"
        my_data = { "labels": {"Code-Review": "+2", "Verified": "+1"} }
        rest.post(query, data=json.dumps(my_data), timeout=30, headers=headers)

Revert Change

對 Gerrit 上的 Change 做 Revert 的動作，如果沒有衝突才能順利進行。

def revert(change, subject):
        headers = {'content-type': 'application/json'}
        query = "/changes/" + str(change) + "/revert"
        my_data = {"message": "{}".format("Revert "+str(subject))}
        rest.post(query, data=json.dumps(my_data), timeout=30, headers=headers) 

Cherry Pick Revision 

對 Gerrit 上的 Change 做 Cherry-pick 的動作，如果沒有衝突才能順利進行。下方 message 裡面放了 Change-Id 的資訊是為了要讓 Gerrit 能夠識別這張 Change 來自哪裡。

def cherrypick(change, subject, change_id, target_branch):
        headers = {'content-disposition': 'attachment', 'content-type': 'application/json'}
        query = "/changes/" + str(change) + "/revisions/current/cherrypick"
        message = """{}

Change-Id: {}""".format(subject, change_id)
        my_data = {"message": "{}".format(message), "destination": "{}".format(target_branch)}
        rest.post(query, data=json.dumps(my_data), timeout=30, headers=headers)

透過 Gerrit REST API 實作遠端操作有一個明顯的優勢，就是當你的專案程式碼非常龐大，Clone 需要花上很多時間的時候，用 Gerrit REST API 操作可以快上許多，或是同樣的動作需要執行很多遍的時候，不妨考慮一下將它自動化吧！剛好泰勞最近有個需求是要將來至四面八方 600 多個的 Change 依序 Cherry-pick 至某條分支，這 API 真的救了我一命阿！ 阿彌陀佛～

GitHubGist:
https://gist.github.com/Kuanlin-Chen/92635ccc132297461558563872ed370a