前言

Gitlab作为一个开源、强大的分布式版本控制系统，已经成为互联网公司、软件开发公司的主流版本管理工具。使用过gitlab的同学都知道，想要提交一段代码，可以通过git push提交到远程仓库，也可以直接在gitlab平台上修改提交。然而上述两种提交方式都是人工提交代码，需要手动登录gitlab或者在第一次commit的时候提供gitlab帐号和密码。那么，假设有这么一个需求场景：我们开发了一个效率平台，可以自动拉分支、自动提交代码到远程仓库。这个需求该如何实现？其实很简单，gitlab提供了一套完整的API，让第三方平台可以通过API自动创建帐号、自动提交代码、自动拉分支，等等。API涉及到的功能非常全面，覆盖了分支、tag、代码提交、用户、群组、项目等，基本上人工可以做的所有操作，都可以通过API自动实现。

身份认证

Gitlab的所有API都需要提供private_token参数进行用户身份认证（除了用来获得private_token的接口本身）。如果没有提供或者提供的private_token不合法，API将会返回401错误码。

{"message":"401 Unauthorized"}

private_token是用来代表用户身份的字符串，和用户是一一对应的关系，http请求中包含这个就可以免输入用户名和密码。

获得private_token的方式有两种：

方法一：查看帐号设置（Profile Settings -> Account）。如下图：

方法二：通过Session API获得Gitlab提供了一个API获取某个用户对应的private_token，这样就能把所有操作都完全自动化起来，也方便了Gitlab与其它系统/平台打通。Session接口需要提供帐号密码来进行身份认证。

API分类介绍

从功能上划分，gitlab API可分为以下几类：

会话（/session）

此类API只包含一个接口，接口的作用是提供用户帐号（或者邮箱帐号）和密码，获得该用户的private_token，后续所有的API都用此token做身份认证。  因为这里的密码是明文提供，所以为了安全起见，最好将gitlab服务部署为https，保证帐号信息不会被非法窃取。

用户帐号（/users）

包括：

1. 查看单个用户信息

2. 查看所有用户信息

3. 查看当前认证用户信息* 帐号的创建、修改、删除、封禁（只有管理员有权限做此操作）

4. SSH Key增删改查（非管理员只能操作自身的，管理员可以操作所有人）

5. 用户邮箱增删改查（非管理员只能操作自身的，管理员可以操作所有人）

群组（Group）和命名空间（Namespace）

Gitlab项目的权限控制是基于命名空间来做的。命名空间包括群组和用户两种。此类API包括命名空间的查询、群组的增删改查等。

项目（/projects）

主要包括：

1. 列出当前用户有权限访问的所有项目

2. 列出当前用户拥有的（owned）所有项目

3. 列出当前用户标星了(starred)的项目

4. 列出所有项目（只有管理员有权限做此操作）

5. 查看单个项目

6. 从新到旧列出某个项目的所有事件（events）

7. 创建、编辑、删除有权限的项目

8. 项目成员操作

9. 项目hooks操作

10. 根据项目名搜索项目（模糊搜索）

分支（Branches）

主要包括：

1. 查看仓库的单个、所有分支

2. 保护（protect）某个分支、去掉某个分支的保护(unprotect)

3. 创建、删除分支

Tags

主要包括：

1. 查看仓库所有tag

2. 创建、删除tag

3. 创建、修改release

项目仓库（Repositories）

主要包括：

1. 查看仓库代码目录树

2. 查看某个文件的明文文本

3. 对比不同分支、tag或者提交(commit)

4. 列出仓库的所有提交人

仓库代码文件（Repository files）

提交代码主要通过操作（CURD, Create, Update, Read, Delete）某个代码文件来完成。和命令行不同的是，用API提交代码时不会有版本冲突，因为它总是用新内容覆盖掉当前文件的内容。

提交（commit）

包括：

1. 查询提交

2. 查看提交的对比（diff）

3. 查询提交的注释（comment）

4. post某次提交的注释

5. 查询某次提交的状态

代码合并（merge）

即操作代码合并，包括合并请求的查询、提交等。

注释（Notes, Comments）

注释的增改查。

项目快照（snippets）

查看、创建、修改、删除一个或者多个项目快照。

项目构建（Builds）

如果使用了gitlab的持续集成功能，可以通过操作构建的API来管理（CURD）所有构建。

一些不常用的功能

包括Issues, Labels, Milestones, Deploy Keys, System Hooks, Settings等的操作。

服务（services）

包括Asana, Assembla, Atlassian Bamboo CI, Buildkite, Campfire, Custom Issue Tracker, Drone CI, Emails on push, External Wiki, Flowdock, Gemnasium, GitLab CI, HipChat, Irker (IRC gateway), JIRAPivotalTracker, Pushover, Redmine, Slack, JetBrains TeamCity CI（再次感叹gitlab服务的强大和全面）。因为都不是特别常用，所以这里不一一介绍，有需要可自行查阅API帮助文档。

使用示例：拉分支

第一步：获取private_token

代码片段：

第二步：新建分支

代码片段：

特别提示

token缓存

如果用户没有手动重置private_token，那么private_token是固定不变的，所以没有必要每次都调API去获取，而是可以将它缓存起来，以提升性能。当遇到API返回401 Unauthorized的情况时，再调Session接口重新获取token并更新缓存。

Http请求方法

特别注意，gitlab api限制了请求的方法，一般查询请求是GET，创建请求是POST，修改请求是PUT，删除请求是DELETE，方法写错了api将返回405 Method Not Allowed错误。

帮助文档

作为一个强大靠谱的服务，gitlab提供了API的帮助文档，上面有注明所有API的使用简单示例。

帮助文档入口：{gitlab_host}/help/api/README.md；或者点击主菜单“Help” -> 点击Documentation底下的API进入，如图所示：

最后

当前笔者正在研究gitlab的源码，后续会分享更多的东西给大家，比如gitlab的api是如何实现的，是否存在安全或者效率的问题，应当如何改进等。