创建合并请求

Tony 在找一些能在他的 Arduino 微控制器上运行的代码，他觉得 https://github.com/schacon/blink 中的代码不错。

但是有个问题，这个代码中的的闪烁频率太高，我们觉得 3 秒一次比 1 秒一次更好一些。 所以让我们来改进这个程序，并将修改后的代码提交给这个项目。

首先，单击“Fork”按钮来获得这个项目的副本。 我们使用的用户名是“tonychacon”，所以这个项目副本的访问地址是： https://github.com/tonychacon/blink 。 我们将它克隆到本地，创建一个分支，修改代码，最后再将改动推送到 GitHub。

$ git clone https://github.com/tonychacon/blink 
Cloning into 'blink'...

$ cd blink
$ git checkout -b slow-blink 
Switched to a new branch 'slow-blink'

$ sed -i '' 's/1000/3000/' blink.ino 

$ git diff --word-diff 
diff --git a/blink.ino b/blink.ino
index 15b9911..a6cc5a5 100644
--- a/blink.ino
+++ b/blink.ino
@@ -18,7 +18,7 @@ void setup() {
// the loop routine runs over and over again forever:
void loop() {
  digitalWrite(led, HIGH);   // turn the LED on (HIGH is the voltage level)
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
  digitalWrite(led, LOW);    // turn the LED off by making the voltage LOW
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
}

$ git commit -a -m 'three seconds is better' 
[slow-blink 5ca509d] three seconds is better
 1 file changed, 2 insertions(+), 2 deletions(-)

$ git push origin slow-blink 
Username for 'https://github.com': tonychacon
Password for 'https://tonychacon@github.com':
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/tonychacon/blink
 * [new branch]      slow-blink -> slow-blink

将派生出的副本克隆到本地

创建出名称有意义的分支

修改代码

检查改动

将改动提交到分支中

将新分支推送到 GitHub 的副本中

现在到 GitHub 上查看之前的项目副本，可以看到 GitHub 提示我们有新的分支，并且显示了一个大大的绿色按钮让我们可以检查我们的改动，并给源项目创建合并请求。

你也可以到“Branches”（分支）页面查看分支并创建合并请求： https://github.com/<用户名>/<项目名>/branches

如果你点击了那个绿色按钮，就会看到一个新页面，在这里我们可以对改动填写标题和描述，让项目的拥有者考虑一下我们的改动。通常花点时间来编写个清晰有用的描述是个不错的主意，这能让作者明白为什么这个改动可以给他的项目带来好处，并且让他接受合并请求。

同时我们也能看到比主分支中所“领先”（ahead）的提交（在这个例子中只有一个）以及所有将会被合并的改动与之前代码的对比。

当你单击了“Create pull request”（创建合并请求）的按钮后，这个项目的拥有者将会收到一条包含关改动和合并请求页面的链接的提醒。

利用合并请求

现在，项目的拥有者可以看到你的改动并合并它，拒绝它或是发表评论。在这里我们就当作他喜欢这个点子，但是他想要让灯熄灭的时间比点亮的时间稍长一些。

接下来可能会通过电子邮件进行互动，就像我们在 分布式 Git 中提到的工作流程那样，但是在 GitHub，这些都在线上完成。项目的拥有者可以审查修改，只需要单击某一行，就可以对其发表评论。

当维护者发表评论后，提交合并请求的人，以及所有正在关注（Watching）这个版本库的用户都会收到通知。我们待会儿将会告诉你如何修改这项设置。现在，如果 Tony 有开启电子邮件提醒，他将会收到这样的一封邮件：

每个人都能在合并请求中发表评论。在 Figure 6-14 里我们可以看到项目拥有者对某行代码发表评论，并在讨论区留下了一个普通评论。你可以看到被评论的代码也会在互动中显示出来。

现在贡献者可以看到如何做才能让他们的改动被接受。幸运的是，这也是一件轻松的事情。如果你使用的是电子邮件进行交流，你需要再次对代码进行修改并重新提交至邮件列表，在 GitHub 上，你只需要再次提交到你的分支中并推送即可。

如果贡献者完成了以上的操作，项目的拥有者会再次收到提醒，当他们查看页面时，将会看到最新的改动。事实上，只要提交中有一行代码改动，GitHub 都会注意到并处理掉旧的变更集。

如果你点开合并请求的“Files Changed”（更改的文件）选项卡，你将会看到“整理过的”差异表 —— 也就是这个分支被合并到主分支之后将会产生的所有改动，其实就是 git diff master...<分支名> 命令的执行结果。你可以浏览 确定引入了哪些东西来了解更多关于差异表的知识。

你还会注意到，GitHub 会检查你的合并请求是否能直接合并，如果可以，将会提供一个按钮来进行合并操作。这个按钮只在你对版本库有写入权限并且可以进行简洁合并时才会显示。你点击后 GitHub 将做出一个“非快进式”（non-fast-forward）合并，即使这个合并 能够 快进式（fast-forward）合并，GitHub 依然会创建一个合并提交。

如果你需要，你还可以将分支拉取并在本地合并。如果你将这个分支合并到 master 分支中并推送到 GitHub，这个合并请求会被自动关闭。

这就是大部分 GitHub 项目使用的工作流程。创建分支，基于分支创建合并请求，进行讨论，根据需要继续在分支上进行修改，最终关闭或合并合并请求。

将合并请求制作成补丁

有一件重要的事情：许多项目并不认为合并请求可以作为补丁，就和通过邮件列表工作的的项目对补丁贡献的看法一样。大多数的 GitHub 项目将合并请求的分支当作对改动的交流方式，并将变更集合起来统一进行合并。

这是个重要的差异，因为一般来说改动会在代码完成前提出，这和基于邮件列表的补丁贡献有着天差地别。这使得维护者们可以更早的沟通，由社区中的力量能提出更好的方案。当有人从合并请求提交了一些代码，并且维护者和社区提出了一些意见，这个补丁系列并不需要从头来过，只需要将改动重新提交并推送到分支中，这使得讨论的背景和过程可以齐头并进。

举个例子，你可以回去看看 Figure 6-15，你会注意到贡献者没有变基他的提交再提交一个新的合并请求，而是直接增加了新的提交并推送到已有的分支中。如果你之后再回去查看这个合并请求，你可以轻松地找到这个修改的原因。点击网页上的“Merge”（合并）按钮后，会建立一个合并提交并指向这个合并请求，你就可以很轻松的研究原来的讨论内容。

与上游保持同步

如果你的合并请求由于过时或其他原因不能干净地合并，你需要进行修复才能让维护者对其进行合并。GitHub 会对每个提交进行测试，让你知道你的合并请求能否简洁的合并。

如果你看到了像 Figure 6-16 中的画面，你就需要修复你的分支让这个提示变成绿色，这样维护者就不需要再做额外的工作。

你有两种方法来解决这个问题。你可以把你的分支变基到目标分支中去（通常是你派生出的版本库中的 master 分支），或者你可以合并目标分支到你的分支中去。

GitHub 上的大多数的开发者会使用后一种方法，基于我们在上一节提到的理由：我们最看重的是历史记录和最后的合并，变基除了给你带来看上去简洁的历史记录，只会让你的工作变得更加困难且更容易犯错。

如果你想要合并目标分支来让你的合并请求变得可合并，你需要将源版本库添加为一个新的远端，并从远端抓取内容，合并主分支的内容到你的分支中去，修复所有的问题并最终重新推送回你提交合并请求使用的分支。

在这个例子中，我们再次使用之前的“tonychacon”用户来进行示范，源作者提交了一个改动，使得合并请求和它产生了冲突。现在来看我们解决这个问题的步骤。

$ git remote add upstream https://github.com/schacon/blink 

$ git fetch upstream 
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
Unpacking objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
From https://github.com/schacon/blink
 * [new branch]      master     -> upstream/master

$ git merge upstream/master 
Auto-merging blink.ino
CONFLICT (content): Merge conflict in blink.ino
Automatic merge failed; fix conflicts and then commit the result.

$ vim blink.ino 
$ git add blink.ino
$ git commit
[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \
    into slower-blink

$ git push origin slow-blink 
Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done.
Total 6 (delta 2), reused 0 (delta 0)
To https://github.com/tonychacon/blink
   ef4725c..3c8d735  slower-blink -> slow-blink

将源版本库添加为一个远端，并命名为“upstream”（上游）

从远端抓取最新的内容

将主分支的内容合并到你的分支中

修复产生的冲突

再推送回同一个分支

你完成了上面的步骤后，合并请求将会自动更新并重新检查是否能干净的合并。

Git 的伟大之处就是你可以一直重复以上操作。如果你有一个运行了十分久的项目，你可以轻松地合并目标分支且只需要处理最近的一次冲突，这使得管理流程更加容易。

如果你一定想对分支做变基并进行清理，你可以这么做，但是强烈建议你不要强行的提交到已经提交了合并请求的分支。如果其他人拉取了这个分支并进行一些修改，你将会遇到 变基的风险中提到的问题。相对的，将变基后的分支推送到 GitHub 上的一个新分支中，并且创建一个全新的合并请求引用旧的合并请求，然后关闭旧的合并请求。

参考

你的下个问题可能是“我该如何引用旧的合并请求？”。有许多方法可以让你在 GitHub 上的几乎任何地方引用其他东西。

先从如何对合并请求或议题（Issue）进行相互引用开始。所有的合并请求和议题在项目中都会有一个独一无二的编号。举个例子，你无法同时拥有 3 号合并请求和 3 号议题。如果你想要引用任何一个合并请求或议题，你只需要在提交或描述中输入 #<编号> 即可。你也可以指定引用其他版本库的议题或合并请求，如果你想要引用其他人对该版本库的“Fork”中的议题或合并请求，输入 用户名#<编号> ，如果在不同的版本库中，输入 用户名/版本库名#<编号> 。

我们来看一个例子。假设我们对上个例子中的分支进行了变基，并为此创建一个新的合并请求，现在我们希望能在新的合并请求中引用旧的合并请求。我们同时希望引用一个派生出的项目中的议题和一个完全不同的项目中的议题，就可以像 Figure 6-18这样填写描述。

当我们提交了这个合并请求，我们将会看到以上内容被渲染成这样：Figure 6-19

你会注意到完整的 GitHub 地址被简化了，只留下了必要的信息。

如果 Tony 回去关闭了源合并请求，我们可以看到一个被引用的提示，GitHub 会自动的反向追踪事件并显示在合并请求的时间轴上。这意味着任何查看这个合并请求的人可以轻松地访问新的合并请求。这个链接就像 Figure 6-20中展示的那样。

除了议题编号外，你还可以通过使用提交的 SHA-1 来引用提交。你必须完整的写出 40 位长的 SHA，GitHub 会在评论中自动地产生指向这个提交的链接。同样的，你可以像引用议题一样对“Fork”出的项目中的提交或者其他项目中的提交进行引用。

GitHub 风格的 Markdown

GitHub 风格的 Markdown 增加了一些基础的 Markdown 中做不到的东西。它在创建合并请求和议题中的评论和描述时十分有用。

任务列表

第一个 GitHub 专属的 Markdown 功能，特别是用在合并请求中，就是任务列表。一个任务列表可以展示出一系列你想要完成的事情，并带有复选框。把它们放在议题或合并请求中时，通常可以展示你想要完成的事情。

你可以这样创建一个任务列表：

- [X] 编写代码
- [ ] 编写所有测试程序
- [ ] 为代码编写文档

如果我们将这个列表加入合并请求或议题的描述中，它将会被渲染 Figure 6-22 这样。

在合并请求中，任务列表经常被用来在合并之前展示这个分支将要完成的事情。最酷的地方就是，你只需要点击复选框，就能更新评论 —— 你不需要直接修改 Markdown。

不仅如此，GitHub 还会将你在议题和合并请求中的任务列表整理起来集中展示。举个例子，如果你在一个合并请求中有任务清单，你将会在所有合并请求的总览页面上看到它的进度。这使得人们可以把一个合并请求分解成不同的小任务，同时便于其他人了解分支的进度。你可以在 Figure 6-23看到一个例子。

当你在实现一个任务的早期就提交合并请求，并使用任务清单追踪你的进度，这个功能会十分的有用。

摘录代码

你也可以在评论中摘录代码。这在你想要展示尚未提交到分支中的代码时会十分有用。它也经常被用在展示无法正常工作的代码或这个合并请求需要的代码。

你需要用“反引号”将需要添加的摘录代码包起来。

```java
for(int i=0 ; i < 5 ; i++)
{
   System.out.println("i is : " + i);
}
```

如果加入语言的名称，就像我们这里加入的“java”一样，GitHub 会自动尝试对摘录的片段进行语法高亮。在下面的例子中，它最终会渲染成这个样子： Figure 6-24。

引用

如果你在回复一个很长的评论之中的一小段，你只需要复制你需要的片段，并在每行前添加 > 符号即可。事实上，因为这个功能会被经常用到，它也有一个快捷键。只要你把你要回应的文字选中，并按下 r 键，选中的问题会自动引用并填入评论框。

引用的部分就像这样:

> Whether 'tis Nobler in the mind to suffer
> The Slings and Arrows of outrageous Fortune,

How big are these slings and in particular, these arrows?

经过渲染后，就会变成这样： Figure 6-25

表情符号（Emoji）

最后，我们可以在评论中使用表情符号。这经常出现在 GitHub 的议题和合并请求的评论中。GitHub 上甚至有表情助手。如果你在输入评论时以 : 开头，自动完成器会帮助你找到你需要的表情。

你也可以在评论的任何地方使用 :<表情名称>: 来添加表情符号。举个例子，你可以输入以下文字：

I :eyes: that :bug: and I :cold_sweat:.

:trophy: for :microscope: it.

:+1: and :sparkles: on this :ship:, it's :fire::poop:!

:clap::tada::panda_face:

渲染之后，就会变成这样： Figure 6-27

虽然这个功能并不是非常实用，但是它在这种不方便表达感情的媒体里，加入了趣味的元素。

Note

事实上现在已经有大量的在线服务可以使用表情符号，这里有个列表可以让你快速的找到能表达你的情绪的表情符号：

http://www.emoji-cheat-sheet.com

图片

从技术层面来说，这并不是 GitHub 风格 Markdown 的功能，但是也很有用。如果不想使用 Markdown 语法来插入图片，GitHub 允许你通过拖拽图片到文本区来插入图片。

如果你回去查看 Figure 6-18 ，你会发现文本区上有个“Parsed as Markdown”的提示。点击它你可以了解所有能在 GitHub 上使用的 Markdown 功能。

邮件通知

有人来修改了你的代码，给你发了一个合并请求。 你会收一封关于合并请求的提醒邮件，它看起来像 Figure 6-34。

关于这个邮件有几个要注意的地方。 它会给你一个小的变动统计结果 — 一个包含合并请求中改变的文件和改变了多少的列表。 它还给你一个 GitHub 上进行合并请求操作的链接。 还有几个可以在命令行使用的 URL。

如果你注意到 git pull <url> patch-1 这一行，这是一种合并远程分支的简单方式，无需必须添加一个远程分支。 我们很快会在 检出远程分支._ 讲到它。 如果你愿意，你可以创建并切换到一个主题分支，然后运行这个命令把合并请求合并进来。

还有一些有趣的 URL，像 .diff 和 .patch ，就像你猜的那样，它们提供 diff 和 patch 的标准版本。 你可以技术性地用下面的方法合并“合并请求”：

$ curl http://github.com/tonychacon/fade/pull/1.patch | git am

在合并请求上进行合作

就像我们在 GitHub 流程，_ 说过的，现在你可以跟开启合并请求的人进行会话。 你既可以对某些代码添加注释，也可以对整个提交添加注释或对整个合并请求添加注释，在任何地方都可以用 GitHub Flavored Markdown。

每次有人在合并请求上进行注释你都会收到通知邮件，通知你哪里发生改变。 他们都会包含一个到改变位置的链接，你可以直接在邮件中对合并请求进行注释。

一旦代码符合了你的要求，你想把它合并进来，你可以把代码拉取下来在本地进行合并，也可以用我们之前提到过的 git pull <url> <branch> 语法，或者把 fork 添加为一个 remote，然后进行抓取和合并。

对于很琐碎的合并，你也可以用 GitHub 网站上的 “Merge” 按钮。 它会做一个 “non-fast-forward” 合并，即使可以快进（fast-forward）合并也会产生一个合并提交记录。 就是说无论如何，只要你点击 merge 按钮，就会产生一个合并提交记录。 你可以在 Figure 6-36 看到，如果你点击提示链接，GitHub 会给你所有的这些信息。

如果你决定不合并它，你可以把合并请求关掉，开启合并请求的人会收到通知。

合并请求引用

如果你正在处理 许多 合并请求，不想添加一堆 remote 或者每次都要做一次拉取，这里有一个可以在 GitHub 上用的小技巧。 这是有点高级的技巧，但它相当有用，我们会在 引用规格 有更多的细节说明。

实际上 GitHub 在服务器上把合并请求分支视为一种 “假分支”。 默认情况下你克隆时不会得到它们，但它们还是隐式地存在，你可以很容易地访问到它们。

为了展示这个，我们要用到一个叫做 ls-remote 的低级命令（通常被叫做“plumbing”，我们会在 底层命令和高层命令读到更多相关内容）。 这个命令在日常 Git 操作中基本不会用到，但在显示服务器上有哪些引用（reference）时很管用。

如果在我们之前用过的 “blink” 版本库上使用这个命令，我们会得到一个版本库里所有的分支，标签和其它引用（reference）的列表。

$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d	HEAD
10d539600d86723087810ec636870a504f4fee4d	refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e	refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3	refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1	refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d	refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a	refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c	refs/pull/4/merge

当然，如果你在你自己的版本库或其它你想检查的远程版本库中使用 git ls-remote origin ，它会显示相似的内容。

如果版本库在 GitHub 上并且有打开的合并请求，你会得到一些以 refs/pull/ 开头的引用。 它们实际上是分支，但因为它们不在 refs/heads/ 中，所以正常情况下你克隆时不会从服务器上得到它们 — 抓取过程正常情况下会忽略它们。

每个合并请求有两个引用 - 其中以 /head 结尾的引用指向的提交记录与合并请求分支中的最后一个提交记录是同一个。 所以如果有人在我们的版本库中开启了一个合并请求，他们的分支叫做 bug-fix，指向 a5a775 这个提交记录，那么在 我们的 版本库中我们没有 bug-fix 分支（因为那是在他们的 fork 中），但我们 可以 有一个 pull/<pr#>/head 指向 a5a775。 这意味着我们可以很容易地拉取每一个合并请求分支而不用添加一堆 remote。

现在，你可以像直接抓取引用一样抓取那些分支或提交。

$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
 * branch            refs/pull/958/head -> FETCH_HEAD

这告诉 Git： “连接到 origin 这个 remote，下载名字为 refs/pull/958/head 的引用。” Git 高高兴兴去执行，下载构建那个引用需要的所有内容，然后把指针指向 .git/FETCH_HEAD 下面你想要的提交记录。 然后你可以用 git merge FETCH_HEAD 把它合并到你想进行测试的分支，但那个合并的提交信息看起来有点怪。 然而，如果你需要审查 一大批 合并请求，这样操作会很麻烦。

还有一种方法可以抓取 所有的 合并请求，并且在你连接到远程（remote）的时候保持更新。 用你最喜欢的编辑器打开 .git/config ，查找 origin 远程（remote）。 看起来差不多像下面这样：

[remote "origin"]
    url = https://github.com/libgit2/libgit2
    fetch = +refs/heads/*:refs/remotes/origin/*

以 fetch = 开头的行是一个 “refspec.” 它是一种把 remote 的名称映射到你本地 .git 目录的方法。 这一条（就是上面的这一条）告诉 Git，“remote 上 refs/heads 下面的内容在我本地版本库中都放在 refs/remotes/origin 。” 你可以把这一段修改一下，添加另一个 refspec：

[remote "origin"]
    url = https://github.com/libgit2/libgit2.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

最后一行告诉 Git： “所有看起来像 refs/pull/123/head 的引用应该在本地版本库像 refs/remotes/origin/pr/123 一样存储” 现在，如果你保存那个文件，执行 git fetch：

$ git fetch
# …
 * [new ref]         refs/pull/1/head -> origin/pr/1
 * [new ref]         refs/pull/2/head -> origin/pr/2
 * [new ref]         refs/pull/4/head -> origin/pr/4
# …

现在所有的合并请求在本地像分支一样展现，它们是只读的，当你执行抓取时它们也会更新。 这让在本地测试合并请求中的代码变得超级简单：

$ git checkout pr/2
Checking out files: 100% (3769/3769)， done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'

你的鹰眼系统会发现在 refspec 的 remote 部分的结尾有个 head 。 在 GitHub 那边也有一个 refs/pull/#/merge 引用，它代表的是如果你在网站上按了 “merge” 按钮对应的提交记录。 这甚至让你可以在按按钮之前就测试这个合并。

合并请求之上的合并请求

你不仅可以在主分支或者说 master 分支上开启合并请求，实际上你可以在网络上的任何一个分支上开启合并请求。 其实，你甚至可以在另一个合并请求上开启一个合并请求。

如果你看到一个合并请求在向正确的方向发展，然后你想在这个合并请求上做一些修改或者你不太确定这是个好主意，或者你没有目标分支的推送权限，你可以直接在合并请求上开启一个合并请求。

当你开启一个合并请求时，在页面的顶端有一个框框显示你要合并到哪个分支和你从哪个分支合并过来的。 如果你点击那个框框右边的 “Edit” 按钮，你不仅可以改变分支，还可以选择哪个 fork。

这里你可以很简单地指明合并你的分支到哪一个合并请求或 fork。

改变默认分支

如果你想用 “master” 之外的分支作为你的默认分支，其他人将默认会在这个分支上开启合并请求或进行浏览，你可以在你版本库的设置页面的 "options" 标签下修改。

简单地改变默认分支下拉列表中的选项，它就会作为所有主要操作的默认分支，他人进行克隆时该分支也将被默认检出。

移交项目

如果你想把一个项目移交给 GitHub 中的另一个人或另一个组织，还是设置页面的这个 ＂options＂标签下有一个 “Transfer ownership” 选项可以用来干这个。

当你正准备放弃一个项目且正好有别人想要接手时，或者你的项目壮大了想把它移到一个组织里时，这就管用了。

这么做不仅会把版本库连带它所有的观察和星标数都移到另一个地方，它还会将你的 URL 重定向到新的位置。 它也重定向了来自 Git 的克隆和抓取，而不仅仅是网页端请求。

服务

首先我们来看一下服务。 钩子与服务整合都可以在仓库的设置区块中找到，就在我们之前添加协作者与改变项目的默认分支的地方。 在 “Webhooks and Services” 标签下你会看到与 Figure 6-49 类似的内容。

有许多可以选择的服务，大多数是整合到其他的商业与开源系统中。 它们中的大多数是为了整合持续集成服务、BUG 与问题追踪系统、聊天室系统与文档系统。 我们将会通过设置一个非常简单的例子来介绍。 如果从 “Add Service” 选择 “email”，会得到一个类似 Figure 6-50的配置屏幕。

在本例中，如果我们点击 “Add service” 按钮，每次有人推送内容到仓库时，指定的电子邮件地址都会收到一封邮件。 服务可以监听许多不同类型的事件，但是大多数只监听推送事件然后使用那些数据做一些事情。

如果有一个正在使用的系统想要整合到 GitHub，应当先检查这里看有没有已有的可用的服务整合。 例如，如果正使用 Jenkins 来测试你的代码库，当每次有人推送到你的仓库时你可以启用 Jenkins 内置的整合启动测试运行。

钩子

如果需要做一些更具体的事，或者想要整合一个不在这个列表中的服务或站点，可以转而使用更通用的钩子系统。 GitHub 仓库钩子是非常简单的。 指定一个 URL 然后 GitHub 在任一期望的事件发生时就会发送一个 HTTP 请求到那个 URL 。

通常做这件事的方式是可以设置一个小的 web 服务来监听 GitHub 钩子请求然后使用收到的数据做一些事情。

为了启用一个钩子，点击 Figure 6-49 中的 “Add webhook” 按钮。 这会将你引导至一个类似 Figure 6-51 的页面。

Web 钩子的设置非常简单。 大多数情况下只需要输入一个 URL 与一个密钥然后点击 “Add webhook”。 有几个选项可以指定在哪个事件时想要 GitHub 发送请求 — 默认的行为是只有当某人推送新代码到仓库的任一分支时的 push 事件获得一个请求。

让我们看一个设置处理 web 钩子的 web 服务的小例子。 我们将会使用 Ruby web 框架 Sinatra，因为它相当简洁，应该能够轻松地看到我们正在做什么。

假设我们想要在某个特定的人推送到我们的项目的特定分支并修改一个特定文件时得到一封邮件。 我们可以相当容易地使用类似下面的代码做到：

require 'sinatra'
require 'json'
require 'mail'

post '/payload' do
  push = JSON.parse(request.body.read) # parse the JSON

  # gather the data we're looking for
  pusher = push["pusher"]["name"]
  branch = push["ref"]

  # get a list of all the files touched
  files = push["commits"].map do |commit|
    commit['added'] + commit['modified'] + commit['removed']
  end
  files = files.flatten.uniq

  # check for our criteria
  if pusher == 'schacon' &&
     branch == 'ref/heads/special-branch' &&
     files.include?('special-file.txt')

    Mail.deliver do
      from     'tchacon@example.com'
      to       'tchacon@example.com'
      subject  'Scott Changed the File'
      body     "ALARM"
    end
  end
end

这里我们拿到一个 GitHub 传送给我们的 JSON 请求然后查找推送者，他们推送到了什么分支以及推送的所有提交都改动了哪些文件。 然后我们检查它是否与我们的条件区配，如果匹配则发送一封邮件。

为了开发与测试类似这样的东西，在设置钩子的地方有一个漂亮的开发者控制台。 可以看到 GitHub 为那个 webhook 的最后几次请求。 对每一个钩子，当它发送后都可以深入挖掘，检测它是否是成功的与请求及回应的消息头与消息体。 这使得测试与调试钩子非常容易。

开发者控制台的另一个很棒的功能是可以轻松地重新发送任何请求来测试你的服务。

关于如何编写 web 钩子与所有可监听的不同事件类型的更多信息，请访问在 https://developer.github.com/webhooks/ 的 GitHub 开发者文档。