Gerrit工作流程及使用手冊

今天偶然看了下圖片的流量，發現這篇講Gerrit的流量好高，果然一看這篇blog的閱讀量已經好幾萬了。為了不誤導大家，我還是做下更新：
本人已經很久不使用Gerrit了，現在用GitLab，界面非常美觀，使用方法也很簡單，而且也能滿足之前的代碼審核的要求。所以大家也都轉去GitLab吧。
關於GitLab的搭建和使用網上應該有很多介紹，這里就不做過多的介紹，我這里有一篇GitBook和GitLab搭建使用的文章，如果要使用GitLab的CI功能，可以參考一下http://lipeng1667.github.io/2019/01/15/public-doc-with-gitlab-ci-writing-with-gitbook/

---

上一篇文章中，我們介紹了如何安裝和正確配置gerrit，相對於gerrit的使用，它的安裝真的算簡單的了。
gerrit的流程、權限控制其實對於初次接觸的同學們來說，確實有點復雜。我希望這篇文章過后，我們能對gerrit的流程有一個大致的了解。
這篇文章將用一個真實的例子，演示一下gerrit的管理員，普通項目成員是如何協同完成項目管理工作的。

這篇文章首先會大致講解下gerrit的工作流程；然后介紹管理員的相關配置工作，包括設置SSH密鑰驗證，添加新成員；接下來會用一個示例演示普通成員push一個commit之后，代碼審核員是如何進行審核的；最后介紹一下如何使用sourceTree上傳代碼到gerrit服務器。

提醒：
這篇文章需要一定的git基礎，如果你還不熟悉git，請先學習下關於git的相關知識。
這篇文章中的所有操作不再需要登錄到gerrit服務器上去了，因為所有的操作都是在管理員或者普通成員的電腦上完成的，至於管理員對組員的操作，也可以在管理員自己的電腦上通過SSH連接到gerrit服務器上完成。

gerrit工作流程

好不容易在google上找了一篇相對簡單明了的介紹gerrit工作流程的圖：

使用過git的同學，都知道，當我們git add --> git commit --> git push 之后，你的代碼會被直接提交到repo，也就是代碼倉庫中，就是圖中橘紅色箭頭指示的那樣。

那么gerrit就是上圖中的那只鳥，普通成員的代碼是被先push到gerrit服務器上，然后由代碼審核人員，就是左上角的integrator在web頁面進行代碼的審核(review)，可以單人審核，也可以邀請其他成員一同審核，當代碼審核通過(approve)之后，這次代碼才會被提交(submit)到代碼倉庫(repo)中去。

無論有新的代碼提交待審核，代碼審核通過或被拒絕，代碼提交者(Contributor)和所有的相關代碼審核人員(Integrator)都會收到郵件提醒。
gerrit還有自動測試的功能，和主線有沖突或者測試不通過的代碼，是會被直接拒絕掉的，這個功能似乎就是右下角那個老頭(Jenkins)的任務。

整個流程就是這樣。 在使用過程中，有兩點需要特別注意下：

1. 當進行commit時，必須要生成一個Change-Id，否則，push到gerrit服務器時，會收到一個錯誤提醒。

2. 提交者不能直接把代碼推到遠程的master主線(或者其他遠程分支)上去。這樣就相當於越過了gerrit了。 gerrit必須依賴於一個refs/for/*的分支。

   假如我們遠程只有一個master主線，那么只有當你的代碼被提交到refs/for/master分支時，gerrit才會知道，我收到了一個需要審核的代碼推送，需要通知審核員來審核代碼了。
   當審核通過之后，gerrit會自動將這條分支合並到master主線上，然后郵件通知相關成員，master分支有更新，需要的成員再去pull就好了。而且這條refs/for/master分支，是透明的，也就是說普通成員其實是不需要知道這條線的，如果你正確配置了sourceTree，你也應該是看不到這條線的。

這兩點很重要！！這兩點很重要！！這兩點很重要！！

這兩點在稍后的示例中，我們會依次介紹。

管理員配置

在上一篇文章的最后，我們做為管理員，初次登錄到了gerrit的web頁面中，接下來還有很多內容需要設置一下。我們依次來看看吧。

profile

初次登錄時，Full Name 和 Email Address 字段都是空的，待會我們會一一設置。沒有設置之前，右上角顯示的用戶名稱也是admin

Preferences

Preferences頁面用於配置gerrit的web頁面，我一般把時間格式改成習慣的24小時制，同時確保Email Nofification處於開啟狀態，這個默認就是開啟的；然后在Show Change Number In Changes Tables打上勾，這樣能清楚地看到每個審核的編號，郵件里面顯示的也是這個編號。

Watched Projects

這里有必要先說一下gerrit的兩個默認項目：

我們點擊左上方的菜單欄 Projects –> List，就能看到兩個默認的項目All-Projects和 All-Users，這兩個工程是兩個基礎的工程，我們新建的工程默認都是繼承自All-Projects的權限。關於權限部分我們在后面的章節詳細介紹。

所以在Watched Projects菜單中，就是當前用戶要監聽的項目，當這些項目發生變化時，你會收到郵件提醒，如果你選擇了All-Projects，那么就意味着你要監聽所有的工程，因為所有工程都會默認繼承自All-Projects。

注意，后面的那些選項，勾選了某一項，就表示僅僅給當前項發送郵件提醒，保險期間，我們就全部勾上就好了。

Contact Information

這里是當前賬號的配置，你可以在這里把full-name填寫完全，這樣右上角也會同步更新你剛設置好的名稱。

注意這里的Preferred Email有兩種設置方法：

1. 如果你的郵件服務器配置完成了(不清楚如何配置的同學請參見上一篇文章)，可以點擊Register New Email，你就會收到一封確認郵件，確認之后就能設置好了。
2. 通過SSH在命令行中進行配置，通過命令行進行配置是最方便快捷，也是最優先推薦的方法。

不過因為SSH命令行的方式需要配置SSH公鑰，所以我們這里先留空，一會通過命令行來配置。

SSH Public Keys

這里需要把你的公鑰內容拷貝出來，然后粘貼到對話框中。我簡單演示下如何操作。

生成公私鑰對

如果你之前有使用過git，那你一定已經生成了公私鑰對，可以直接跳過這個步驟。
在命令行中輸入下面的內容：

1	$ ssh-keygen -t rsa

然后會提示你輸入一個密碼，用來訪問公私鑰，可以直接回車表示不加密碼。接下來就會自動幫你創建好一對公私鑰了。

找到公鑰文件

默認公私鑰的是放置在~/.ssh目錄下的，默認的名稱是id_rsa和id_rsa.pub。其中.pub文件就是公鑰，私鑰你自己需要保存好。我們來看下我的.ssh文件夾中的內容

• config是ssh的配置文件，稍后我們會演示通過管理員ssh連接到gerrit服務器時，會在來看這個文件
• lipeng和lipeng.pub分別是我的私鑰和公鑰

我們要做的，就是把公鑰的內容拷貝出來，然后粘貼到頁面上去。
注意拷貝時，要從RSA開始拷貝，如果格式不對，頁面上會有提示。
還有一點要說明的是，這些都是在你想要作為管理員賬號的機器上操作完成，對我來說，我的macbook就是管理員要使用的電腦。

Groups

最后來看一下gerrit的分組。圖片里面是gerrit默認的幾個分組，我們需要知道的是Administrator就是管理員分組，Anonymous Users指的是所有添加到gerrit數據庫中的成員都默認加入的一個組。之后我們還可以建立新的分組，加入新的成員等等。

示例

接下來我們來做一個演示，看看一個新的成員是如何被添加到gerrit服務器中，然后他們又是如何協同工作的。
這里一共涉及到兩個角色，一個是管理員，一個是普通成員。

管理員設置SSH

在之前的文章中我們提到過，gerrit自帶的H2數據庫就完全夠用了，對成員的管理，郵件添加等操作，均可以通過SSH來完成。那第一步我們就來看一下管理員如何才能遠程SSH到gerrit服務器。

首先確保在之前，已經成功把你的公鑰添加到了web頁面賬戶中。
接下來，需要修改之前~/.ssh/文件夾下面的config文件，我們拿我的config文件做為示例，做個講解。

我們還是先進入到~/.ssh/文件夾中

然后查看一下config文件： vim config

我們看到這里面有兩個Host部分，我們重點來看第2個Host部分，這個是我們新建的，用於連接到gerrit服務器的配置。

照貓畫虎，對於我們之前建立在192.168.1.100的gerrit服務器來說，你的Host配置可能如下：

1 2 3 4 5

Host gerrit HostName "192.168.1.100" User "admin" IndentityFile "~/.ssh/id_rsa" port 29418

User要和我們在gerrit服務器上注冊的名稱保持一致( 不是 full-name)，認證文件注意要和公鑰對應的私鑰文件，端口要填寫gerrit服務的端口號，這里是默認的29418。

配置完config文件，我們就可以SSH到gerrit了，我們來嘗試一下吧：

我們在管理員的機器上，輸入ssh gerrit -l admin命令，就可以得到gerrit服務器的響應，只不過因為我們禁用了shell，所以連接很快斷開了，沒有關系，這樣證明做為管理員，已經可以通過命令行對gerrit服務器進行一系列的操作了。

添加普通成員

在管理員添加新的組員之前，我們需要先在普通成員的機器上生成ssh的公私鑰，這里方便描述，我們把這個普通成員命名為test3。

在test3的電腦命令行中，生成利用ssh-keygen命令，生成公私鑰。

我們就使用默認的id_rsa命名好了。

接下來，test3成員需要把id_rsa.pub公鑰發送給管理員，這樣管理員才能正常把test3添加到gerrit用戶組中。
我們假設管理員將test3的pub公鑰放到了~/home目錄下，也就是說，在管理員的電腦上，test3的公鑰存放在~/home/id_rsa.pub文件，當然我們也可以重新把它命名為test3.pub，方便演示我這里就不做更名處理了，

接下來，管理員在命令行中輸入如下的命令來完成添加普通成員的操作。注意： 這個命令很強大很方便，可以一步到位地把成員的的名稱，全名，郵箱以及ssh公鑰認證全部設置好。

1	$ cat ~/home/id_rsa.pub | ssh gerrit gerrit create-account --full-name test3 --email [e-mail] --ssh-key - test3

接下來我們來詳細看一下這個命令：

• | 符號把這個命令分成了兩部分，第一部分的cat ~/home/id_rsa.pub表示把test3的公鑰內容讀入到輸入流中
• ssh gerrit是我們之前在~/.ssh/config中配置好的gerrit服務器地址
• 又接着一個gerrit表示通過ssh中輸入gerrit命令來進行相關操作
• create-account 表示要新建用戶。注意，新建的用戶名寫在最后面，中間是其他參數
• full-name 就如同頁面中的全名，我們這里命名為test3
• email表示該用戶的email地址，我們填入 [e-mail]
• ssh-key - 注意，最后的- 表示從輸入流中讀取ssh的公鑰內容，也就是 | 符號之前我們讀入的test3用戶公鑰內容
• 最后面加上我們要create的用戶名稱

這個命令執行完之后，管理員就把test3用戶加入到了gerrit用戶組中，並且設置了他的全稱，郵件以及公鑰文件，是不是一步到位，非常方便？？

這里我們回過頭來，在管理員首次登陸web頁面進行修改配置的時候，我們說過，管理員的郵箱可以通過命令行來設置，是的，同樣通過ssh命令行：

1	$ ssh gerrit gerrit set-account --add-email [e-mail] admin

這個命令就表示為我們的admin用戶添加email`[e-mail]`。執行完這個命令，再回到web界面上的用戶設置界面，看看是不是管理員的email已經被設置好了？？

修改用戶所在組

接下來我們看一下怎樣修改test3用戶所在的組吧。我們知道他已經出在Anonymous Users組中了，那我們想要新建一個組，就叫test_user吧，我們來看一下

我們在gerrit頁面的頂部，點擊People –> list， 看一下默認的兩個分組，Administrator和Non-interactive Users，這兩個分組我們都能從字面上理解是什么意思。我們注意到Anonymous Users這個分組並沒有顯示在頁面，因為它是匿名的嘛，所有的用戶自動添加到這個分組中了。

選擇Create New Group，輸入我們要添加的新的分組 test_user

新的分組中，我們看到管理員的賬號被自動添加了進來

我們在Add搜索欄中輸入test，就會自動顯示出來管理員之前在命令行中創建的test3用戶，看到full-name和email了吧，都已經添加完成了！
test3用戶已經添加到了test_user分組中了。

新建和修改項目

用同樣的方法，我們來新建一個項目吧

點擊Project，然后Create New Project， 創建一個名為test2的項目吧。

可以通過點擊project名稱，進入到工程的詳細設置界面。

點擊頂部菜單欄中的Access，來設置這個項目的權限吧。
我們可以看到這個項目已經有了個默認的繼承自All-Projects的權限，關於默認的權限這里不做多的介紹，想要深入學習的同學可以點擊進去看一下。

修改權限的時候慎重，不要直接修改All-Projects組的權限，因為這個是所有項目的依賴權限組，修改了以后，所有的項目權限都會跟着發生變化。

我們點擊Edit按鈕來修改這個項目的權限

我們把Reference改成refs/*，表示所有的refs下的分支
然后選擇read項目

接着篩選不同的分組，並且賦予不同的權限。

• 我們把Anonymous Users分組中的用戶設置為DENY
• 把我們剛建立好的，並且添加了test3用戶的test_user分組權限設置為ALLOW

這樣，當前的工程就只能被test_user組內的用戶所訪問，其他組的用戶均無法訪問了！

test3用戶clone工程

接下來我們來到test3用戶的電腦上，下拉剛剛創建的test2工程

在命令行執行下面的命令，就可以把test2工程給clone下來了

1	$ git clone ssh://test3@192.168.1.100:29418/test2.git

對比下，會發現我們的目錄中多了一個名為test2的文件夾，這個就是我們的工程了！

注意如果從ssh方式clone下來的工程，里面是自帶了hooks文件夾的，這個文件夾很重要！！如果不是用ssh://方式克隆下來的，還沒有這個文件夾，需要我們自己mkdir

我們直接新建一個test.md文件，來嘗試着往遠程提交。

注意： 前方會出現很多錯誤，耐心一步一步來

提交

首先我們通過下面兩個命令首先commit到本地倉庫：

1 2	$ git add test.md $ git commit

在commit的時候，發現提交者的名稱和email都是錯誤的，我們需要先配置成我們當前的test3用戶，以及對應的email

1 2	$ git config user.name test3 $ git config user.email [e-mail]

通過git config --list來查看一下當前git倉庫的配置，發現已經把用戶名和密碼正確設置了。

接下來我們繼續git commit來提交到本地

我們把這次提交命名為commit_1，然后我們通過git push命令來推送

發現推送失敗了，提示的錯誤是：

You are not allowed to perform this operation
[remote rejected] master -> master (prohibited by Gerrit)

Gerrit拒絕了我們直接提交到master的推送！

這就是我們在文章開頭提到的問題，我們需要push到refs/for/master那條線上！！

那怎么辦呢？？
我們在命令行寫入下面的命令：

1	$ git config remote.origin.push refs/heads/*:refs/for/*

這行命令的意思是，當執行push命令時，將會推送到refs/for/當前head所在的分支上。

我們設置了push命令之后，重新進行push，結果又報錯了。。
這次的錯誤是：

missing Change-Id in commit message footer

這個是提到的第2個問題，commit一定要有Change-Id
然后我們看到了命令行中給了我們提示，我們可以從hooks文件中拷貝commit-msg文件下來，這樣commit時，會自動幫我們生成Change-Id.

我們可以看一下 git rev-parse --git-dir就是指向的當前git配置的文件，就是.git文件夾
所以我們直接用scp命令從gerrit服務器上拉取當前用戶的hooks文件。

1	$ scp -p -P 29418 test3@192.168.1.100:hooks/commit-msg .git/hooks/

然后我們重新push發現一樣的錯誤，因為我們還停留在上次commit，上次的commit是沒有生成Change-Id的！

沒有關系，我們回退一下，然后重新提交。
回退命令是先用git log找到上一次的commit id， 然后用git reset --hard 找到的id命令回退

這次我們終於提交成功了，可以看到提交到的分支是refs/for/master

管理員審查

接下來我們回到管理員的web頁面，會發現，test3用戶剛提交的那條已經在頁面中了
點擊頂部的My --> Watched Changes

因為之前我們已經監聽了All-Projects，而test2工程又是默認繼承自All-Projects的，所以我們就可以收到了，如果當前管理員沒有監聽All-Projects，就需要手動把test2項目加進來，否則是不會在watched頁面看到這條推送提醒的。

與此同時，我們會收到來自[e-mail]發送來的郵件了：

事件處理

我們通過點擊commit_1可以進入到當前事件的詳情頁面：

可以在頁面中看到我們生成的Change-Id，以及我們新添加的文件test.md，點擊以后可以看到每個文件的詳情。
注意屏幕中間的兩個按鈕：

• Reply 表示對這次事件的回應，里面可以有5個選項，表示當前審查人員對這個事件的打分：-2，-1，0，+1，+2， +2表示直接同意，1表示我同意了，需要別的人員來一起審核
• Code-Review+2 相當於直接打+2分

我們還可以通過點擊右邊的小人，來添加新的審核人員

reply之后，如果分數夠了2分，就可以直接submit到主線上去了

合並了之后，可以在 My --> Changes 中看到我們的審核歷史

到這里，一個完整的從普通項目成員提交，到代碼審核人員檢查的全過程，就結束了。

SourceTree

SourceTree是git的可視化工具，也是比較流行的git工具，通過sourceTree我們一樣可以commit，push等，而且更方便直觀地看到項目的歷史等等。

在上面的示例中，我們都是通過命令行來完成git的相關操作的，那通過soureTree，我們同樣需要注意那兩點：

1. commit時要有Change-Id
2. push一定要到refs/for/master分支上

這里還需要額外注意一點：

• 如果我們是通過soureTree工具clone項目，而不是通過ssh://方式來clone，那么工程中的.git文件夾中是沒有hooks文件夾的，需要我們手動去文件夾中創建

我們在管理員的視角從gerrit服務器上拉取之前的test2工程吧：

• Source URL中填入gerrit:test2.git。 因為我們之前已經在.ssh/config文件中設置好了名為gerrit的HOST所以這里就可以簡寫了

可以看到test3用戶提交的commit_1，因為已經通過審核了，所以，就合並到master中了

我們到當前的目錄中，看一下.git文件夾，確實是沒有hooks文件夾的

我們通過scp gerrit:hooks/commit-msg hooks/命令來拉取commit-msg文件

同時通過git config remote.origin.push refs/heads/*:refs/for/*命令來設置push命令

設置自定義push

雖然我們設置好了push命令到遠程的refs/for/*目錄，但是如果我們直接用SourceTree中的push功能，我們會發現直接給我們在遠程新建了一個refs/for/*分支，而且gerrit也沒有審核事件觸發，這是因為sourceTree的push應該是有它自己的一些配置，所以這里我們需要自定義push事件，來完成將代碼推送到正確的分支上。

我們進入SourceTree的配置頁面

點擊Custom Actions，然后輸入命令的名字： push to gerrit

• Script to run： 指的是要執行的文件，我們這里把git的可執行文件目錄放進來，如果是windows請自行找到該目錄
• Parameters 就直接寫入push，表示執行的是push命令

最后當我們要通過推送到gerrit服務器時，在當前的分支上，右鍵，然后點擊Custom Actions，再選擇我們剛創建的push to gerrit動作，就實現了推送到gerrit服務器的功能！！

好了，到這里，關於gerrit的所有內容都介紹完了！！！

 

轉載：http://lipeng1667.github.io/2017/01/18/gerrit-guide/