Git、Gerrit与Jenkins/Hudson CI服务器

作者：Alex Blewitt，发布于2012-2-28

本文讲述了如何为基于团队的代码审查系统配置Git、Gerrit与Jenkins/Hudson，正如我在《Git, Gerrit and Jenkins for iOS development》和《Gerrit Git Review with Jenkins CI Server》演讲（以及第一次提出这种做法的《Someday...》）中所倡导的那样。文中的范例假定你所使用的操作系统是OS X或Linux，但是如果你愿意，也可以在Windows上运行它们。

配置Git

很多系统（例如Linux）已经默认提供了Git，在Git主页也可以找到安装程序。对于Windows用户，最好的选择是MsysGit。请注意，如果你安装了Apple Developer Tools (for Xcode 4)，那么其中已经自带Git二进制包了。如果遇到了问题，help.github.com中可以找到很多非常出色的指南。

因为所有的Git提交都带有作者和电子邮件地址，如果你还没有设置过这些内容，请执行以下命令进行配置：

$ git config --global user.name "Alex Blewitt"

$ git config --global user.email Alex.Blewitt@example.com

最好有一个Git代码库。Gerrit在初始化阶段会自动扫描Git代码库，这样做比在后期配置代码库容易一些，因此最好在初始化Gerrit前准备好Git代码库。

如果还没有Git代码库，可以创建一个：

git init --bare /path/to/gits/example.git

Gerrit

可以从http://code.google.com/p/gerrit/下载到Gerrit，那是一个WAR文件。Gerrit有很好的文档（目前的最新文档是2.2.1，但也可用于2.1.7）和安装指南。

Gerrit在运行时需要用到数据库（用于存储代码审查的信息）。目前支持的数据库包括H2、PostgreSQL和MySQL。在没有进行额外配置的情况下，它默认使用H2。

请注意，Gerrit 2.2.x正把项目配置、权限和其他元数据移到Git存储中，这样就可以通过Git进行访问和版本控制。在2.2.x中，这个转变会慢慢扩展到其他类型的元数据上，包含代码评审内容。详见2.2.0版本的发布说明。

要初始化Gerrit，运行java -jar gerrit.war init -d /path/to/location会在指定路径上安装Gerrit运行时。

如果是在交互终端中运行的，安装程序会提几个问题，例如：

Git代码库的位置 [git]
导入现有代码库 [Y/n]
数据库服务器类型 [H2/?]
身份验证方法 [OPENID/?]
SMTP服务器主机名 [localhost]
SMTP服务器端口 [(default)]
SMTP加密 [NONE/?]
SMTP用户名
以何种身份运行 [you]
Java运行时 [/path/to/jvm]
将gerrit.war复制到/path/to/location/bin/gerrit.war [Y/n]
监听地址 [*]
监听端口 [29418]
下载并安装Bouncy Castle [Y/n]
位于HTTP反向代理之后 [y/N]
使用SSL [y/N]
监听地址 [*]
监听端口 [8080]

其中大部分可以保留默认值，但是有几个需要重点关注。

Git代码库的位置要指向正确的位置。默认值是位于安装目录中的'git'目录，也可以是其他不同位置（例如/var/gits等等）。应该先配置好这个路径，因为在Gerrit启动时它会先扫描该目录来添加新项目。
监听地址对有多个地址（例如IPv4和IPv6）的主机很有用，它可以限定使用哪个地址。*表示本地主机上的任意地址。
监听端口是一个端口号。29418是默认的Gerrit SSH端口，而8080是默认的Gerrit Web端口。但是如果8080已经被别的应用程序占用了，那么你可能会想修改第二个端口。
身份验证方法确定了如何登录Gerrit。如果你想挂入某个现有的身份验证提供方（例如Google Accounts），那么可以使用OpenID。但对测试而言（还有上面提到的范例），可以使用development_become_any_account。键入?会显示一个可用方法的列表。

Gerrit启动后，会打开一个浏览器，显示Gerrit主页。登录的第一个用户将自动成为管理员；所有后续登录的用户都是无权限用户。如果你选择了development_become_any_account，在页面顶端会有一个Become链接，通过它可以进入注册/登录页面。

注册用户

为了使用Gerrit，你需要一个账号，生成一个SSH密钥对。在命令行中运行 ssh-keygen -t rsa -b 2048可以生成密钥对，将其放到你的.ssh目录中。如果你需要更多信息，可以访问这篇博文，这是我六年前写的SSH密钥相关文章。此外，GitHub 帮助页面中也有更多相关信息。

默认文件名为id_rsa（这是私钥）和id_rsa.pub（这是公钥）。你只能给别人公钥，千万别给别人私钥。

有了密钥，你就可以在Gerrit中注册新账户了。点击顶部右端的“Become”链接，然后再点击“New account”按钮，输入Git知道的名称和电子邮件（即上面用git config配置的），这些内容要完全匹配（包括大小写）。保存变更，然后选择一个唯一的用户名（填入了名称后点击'select username'，例如demo）。

头痛的电子邮件就算是development_become_any_account模式，Gerrit也会给你发送电子邮件以验证邮件地址。不通过验证的话就无法使用该电子邮件地址，你也无法提交代码。

我们可以很快处理掉这个问题，因此如果Gerrit目前不让你注册你的邮箱地址，请不用担心。

在'add SSH public key'文本框中，添加.pub文件中的公钥。如果你使用的是OS X，pbcopy < ~/.ssh/id_rsa.pub就可轻松搞定。记住要点击“Add”保存公钥。

点击Continue后应该就能登录到Gerrit的主窗口了。到目前为止一切还不错，现在可以测试SSH的连通性了。

键入ssh -p 29418 demo@localhost会尝试连接Gerrit服务器，会出现以下三者之一：

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!

这并没有看上去那么糟。它只是说你的~/.ssh/known_hosts文件中有旧的密钥。最懒的一种修复方法是删除这个文件（这是GitHub推荐的做法）。更好的方法是找到提示出错的那一行，把它删了：

Offending key in /Users/demo/.ssh/known_hosts:123

你可以用任何文本编辑器来删除known_hosts文件中的第123行。在标准UNIX配置下，可以用以下命令自动删除：

sed -i '' '123d' ~/.ssh/known_hosts

The authenticity of host '[localhost]:29418 ([::1]:29418)' can't be established.

RSA key fingerprint is e8:e2:fe:19:6f:e2:db:c1:05:b5:bf:a6:ad:4b:04:33.

Are you sure you want to continue connecting (yes/no)? yes

Warning: Permanently added '[localhost]:29418' (RSA) to the list of known hosts.

Permission denied (publickey).

如果看到这个消息，说明Gerrit没有识别出你提交的任何密钥。ssh默认会发送id_rsa，要确认它的确发送了该值，可以查看.ssh/config，文件头上有一行IdentityFile ~/.ssh/id_rsa。可以运行ssh -v查看发送的内容：

debug1: Next authentication method: publickey

debug1: Trying private key: /Users/demo/.ssh/id_dsa

debug1: Offering public key: /Users/demo/.ssh/id_rsa

假设已经发送了正确的密钥，那么在settings - ssh public keys菜单项中检查该密钥是否关联了Gerrit中的用户。如果没有的话点击'Add Key'并和之前一样粘贴公钥。

如果Gerrit还是说你未经身份验证，检查用户名和配置页面里的用户名是否一致。如果用户名不同，试试ssh -p 29418 username@localhost。

最后，要验证具体的密钥，可以运行ssh -i ~/.ssh/id_rsa显式地选择要使用的密钥，而不是让它自动选择密钥。如果这样可以工作，但不带-i参数却不行的话，那么问题出在你的~/.ssh/config文件里――你需要保证选择了合适的IdentityFile。

**** Welcome to Gerrit Code Review ****

Hi demo, you have successfully connected over SSH.

Unfortunately, interactive shells are disabled.

To clone a hosted Git repository, use:

git clone ssh://demo@localhost:29418/REPOSITORY_NAME.git

Connection to localhost closed.

如果看到这个提示，说明Gerrit已经正常工作了。

修正电子邮件地址

如果之前你无法在Gerrit中注册电子邮件地址，那么可以手工进行注册。我们可以停止Gerrit，运行GSQL工具更新特定数据字段。

$ bin/gerrit.sh stop

$ java -jar bin/gerrit.war gsql

Welcome to Gerrit Code Review 2.1.6.1

(H2 1.2.134 (2010-04-23))

Type '\h' for help. Type '\r' to clear the buffer.

gerrit> select * from ACCOUNT_EXTERNAL_IDS;

ACCOUNT_ID | EMAIL_ADDRESS | PASSWORD | EXTERNAL_ID

-----------+------------------------+----------+------------------------------------------

1000000 | NULL | NULL | uuid:ac1b8a08-2dd1-4aa1-8449-8b2994dffaed

1000000 | NULL | NULL | username:demo

(2 rows; 23 ms)

gerrit> update ACCOUNT_EXTERNAL_IDS set EMAIL_ADDRESS='alex.blewitt@example.com' where ACCOUNT_ID=1000000;

UPDATE 2; 5 ms

gerrit> select * from ACCOUNT_EXTERNAL_IDS;

ACCOUNT_ID | EMAIL_ADDRESS | PASSWORD | EXTERNAL_ID

-----------+------------------------+----------+------------------------------------------

1000000 | alex.blewitt@example.com | NULL | uuid:ac1b8a08-2dd1-4aa1-8449-8b2994dffaed

1000000 | alex.blewitt@example.com | NULL | username:demo

(2 rows; 23 ms)

gerrit> \q

Bye

$ bin/gerrit.sh start

创建项目，克隆并推送代码

开始前，我们需要先在Gerrit中创建一个项目。如果Gerrit没有在你的范例目录中检测到项目，在它运行时，我们可以创建一个项目。

$ ssh -p 29418 demo@localhost gerrit create-project --name example.git

上述命令会创建一个名为example的项目，在之前指定的Git目录里初始化一个空的代码库。如果已经有一个代码库了，Gerrit不允许创建同名代码库——但你可以先对它进行临时重命名，随后再把名字改回来。

随后，可以创建一个克隆：

$ git clone ssh://demo@localhost:29418/example.git

Cloning into example...

warning: You appear to have cloned an empty repository.

我们可以向代码库进行提交和推送，就和其他Git系统一样：

$ cd example

$ echo hello > world

$ git add world

$ git commit -m "The World"

[master (root-commit) 06bf85e] The World

1 files changed, 1 insertions(+), 0 deletions(-)

create mode 100644 world

$ git push

No refs in common and none specified; doing nothing.

Perhaps you should specify a branch such as 'master'.

$ git push origin master

Counting objects: 3, done.

Writing objects: 100% (3/3), 217 bytes, done.

Total 3 (delta 0), reused 0 (delta 0)

To ssh://me@localhost:29418/example.git

! [remote rejected] master -> master (prohibited by Gerrit)

error: failed to push some refs to 'ssh://demo@localhost:29418/example.git'

这是什么情况？Gerrit不希望我们直接覆写Git代码库中的任何分支，而是将变更推送到另一个refspec中，这让Gerrit有机会在代码审查中修改代码。最简单的方法是为推送配置一个默认的refspec：

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

$ git push origin

Counting objects: 3, done.

Writing objects: 100% (3/3), 217 bytes, done.

Total 3 (delta 0), reused 0 (delta 0)

To ssh://demo@localhost:29418/example.git

* [new branch] master -> refs/for/master

我们推送了一个分支，在Gerrit的change,1里可以发现，尽管实际的分支名称是refs/changes/01/1/1，但看到的却是refs/for/master。你会发现当前分支的哈希值和此处显示的一样（在我的例子里是06bf85e）。如果我们要再次推送，会创建一个新的分支refs/changes/02/2/1，而不是覆盖refs/for/master。第一个数字是变更号的最后两位，第二个数字是变更号，第三个数字是补丁集号。所以变更123的补丁集17就是refs/changes/23/123/17。

如果想要修正（amend）提交，Gerrit会创建一个新的代码审查引用，这么做不太好。如果两次变更之间有审查评语，你将丢失这些内容。

我们可以修改commit-msg，添加一个（Gerrit专门的）Change-Id。同一变更的所有后续提交都会关联到一个补丁集上。Gerrit提供了一个实现，只要复制出来就行了。

$ cd .git/hooks

$ scp -P 29418 demo@localhost:hooks/commit-msg .

$ cd ../..

现在，当我们要提交修正时便会自动生成一个Change-Id。可以用这个值为变更集生成多个补丁。通过修正提交，并提供Gerrit变更的Change-Id，我们可以修改当前的提交。

$ git commit --amend -m "Hello World

> Change-Id: I06bf85ed12f370212ec22dbd76c115861b653cf2

> "

[master 86a7a39] Hello World

1 files changed, 1 insertions(+), 0 deletions(-)

$ git push

Counting objects: 3, done.

Writing objects: 100% (3/3), 260 bytes, done.

Total 3 (delta 0), reused 0 (delta 0)

remote: (W) 86a7a39: no files changed, message updated

To ssh://me@localhost:29418/example.git

* [new branch] master -> refs/for/master

现在再去看Gerrit中的change 1，你会发现出现了第二个与该变更相关联的补丁集。远端分支refs/changes/01/1/2包含了新的提交消息（尽管所有文件还是一样的）。

通常情况下，你并不需要添加Change-Id，因为提交消息Hook会自动帮你添加的。

代码审查与结果提交

我们要创建一个build.sh脚本来执行构建过程。Jenkins/Hudson会签出并运行该脚本。一般而言，这是一个Maven的构建，也可能是xcodebuild或make——为了避免针对某种语言，我们就使用一个普通的脚本。

$ cat > build.sh

#!/bin/sh

echo Pretending to build ...

echo done

$ chmod a+x build.sh

$ git add build.sh

$ git commit -m "Adding (dummy) build script"

$ git push

问题是这些变更还在Gerrit的评审队列里，我们要先批准这些变更。进入变更页面，会看到这些文件，还有一个Review按钮。在变更页面有一个让你做代码审查的Review按钮，但却没有提交按钮……

这是因为变更在提交前默认要评审+2，每个人只能+1，也就是说只有一个人做代码审查是无法提交代码的。

我们可以修改Gerrit的规则，允许一个人投票+2，也可以准许+1提交。

最简单的方法是进入项目管理页面的All Projects Access标签页（在Gerrit 2.2.1和2.1.7.2里这个标签从--All Projects--改成了All-Projects）。点击“Code review”规则旁边的复选框，修改“Permitted Range”为+2: Looks good to me, approved。Gerrit还需要一个+1校验，随后也会为Jenkins/Hudson配置的。按照下面内容添加一条新规则：