GitLab API 入门教程：从基础到实践

2025-3-13

GitLab API 入门教程：从基础到实践

引言

在现代软件开发中，自动化和集成是提高效率的关键。GitLab 不仅是一个强大的 Git 仓库管理工具，它还提供了一套全面的 API，允许开发者通过编程方式与其进行交互。通过 GitLab API，你可以自动化各种任务，例如创建项目、管理用户、处理合并请求、触发 CI/CD 流程等。

本教程将带你深入了解 GitLab API，从基础概念到实际应用，让你能够熟练地使用 API 来增强你的开发工作流程。我们将涵盖以下内容：

GitLab API 基础
- 什么是 API？
- GitLab API 的版本
- 认证方式（Personal Access Token、OAuth 2.0、Project Access Token）
- API 端点（Endpoints）和请求方法（GET、POST、PUT、DELETE）
- 分页（Pagination）
- 速率限制（Rate Limits）
- 错误处理
使用 Personal Access Token 进行身份验证
- 创建 Personal Access Token
- 设置 Token 权限（Scopes）
- 在 API 请求中包含 Token
常用的 API 端点及示例
- 用户（Users）
  - 获取当前用户信息
  - 搜索用户
  - 创建用户（管理员权限）
- 项目（Projects）
  - 创建项目
  - 获取项目列表
  - 获取单个项目信息
  - 更新项目
  - 删除项目
- 分支（Branches）
  - 获取分支列表
  - 创建分支
  - 删除分支
- 合并请求（Merge Requests）
  - 创建合并请求
  - 获取合并请求列表
  - 接受合并请求
  - 添加评论到合并请求
- 议题（Issues）
  - 创建议题
  - 获取议题列表
  - 更新议题
- CI/CD 流水线（Pipelines）
  - 获取项目流水线
  - 触发流水线
  - 取消或重试流水线
使用 Python 操作 GitLab API
- 安装 python-gitlab 库
- 初始化 GitLab 客户端
- 执行 API 请求
- 处理 API 响应
- 错误处理和异常捕获
实际案例
- 自动创建项目和初始化仓库
- 批量管理用户
- 根据代码提交自动创建合并请求
- 监控 CI/CD 流水线状态并发送通知
- 定期备份项目
高级主题
- GraphQL API
- Webhooks
总结与进阶资源

1. GitLab API 基础

什么是 API？

API（Application Programming Interface，应用程序编程接口）是一组定义了不同软件组件之间如何交互的规则和规范。它允许你通过代码来访问和操作另一个应用程序的功能，而无需了解其内部实现细节。
GitLab API 的版本

GitLab API 的当前主要版本是 v4。在进行 API 调用时，通常需要在 URL 中指定版本号，例如：https://gitlab.example.com/api/v4/。
认证方式

GitLab API 支持多种认证方式：
- Personal Access Token (PAT)：个人访问令牌是最常用的方式，适用于个人脚本和小型应用程序。你可以为令牌设置不同的权限范围（Scopes）。
- OAuth 2.0：适用于需要代表用户访问 GitLab 的第三方应用程序。它更安全，因为应用程序不需要存储用户的密码。
- Project Access Token: 项目访问令牌类似于个人访问令牌，但是它们仅限于单个项目的范围, 适用于CI/CD.
在本教程中，我们将主要使用 Personal Access Token。
API 端点（Endpoints）和请求方法（GET、POST、PUT、DELETE）

GitLab API 使用 RESTful 架构。每个 API 操作都对应一个特定的端点（URL）和 HTTP 请求方法：
- GET：获取资源（例如，获取项目列表）。
- POST：创建新资源（例如，创建项目）。
- PUT：更新现有资源（例如，更新项目设置）。
- DELETE：删除资源（例如，删除项目）。
分页（Pagination）

当 API 请求返回大量数据时，GitLab API 会使用分页来限制每次返回的结果数量。你可以使用 page 和 per_page 参数来控制分页。例如：
/projects?page=2&per_page=50
这将返回第 2 页的项目，每页包含 50 个项目。
速率限制（Rate Limits）

为了防止滥用，GitLab API 对请求频率进行了限制。如果超出限制，你将收到 HTTP 429 错误（Too Many Requests）。你应该在程序中处理速率限制，例如通过重试机制。
在返回的header信息中，你可以找到和速率限制相关的信息
* RateLimit-Limit
* RateLimit-Observed
* RateLimit-Remaining
* RateLimit-Reset
* RateLimit-ResetTime
错误处理

GitLab API 会返回 HTTP 状态码来指示请求的结果。常见的状态码包括：
- 200 OK：请求成功。
- 201 Created：资源创建成功。
- 204 No Content：请求成功，但没有内容返回（例如，删除操作）。
- 400 Bad Request：请求无效（例如，参数错误）。
- 401 Unauthorized：未授权（例如，缺少或无效的 Token）。
- 403 Forbidden：禁止访问（例如，没有权限）。
- 404 Not Found：资源未找到。
- 500 Internal Server Error：服务器内部错误。
你应该在程序中检查状态码并处理错误。

2. 使用 Personal Access Token 进行身份验证

创建 Personal Access Token
1. 登录 GitLab。
2. 点击右上角的头像，选择 "Preferences"。
3. 在左侧导航栏中，选择 "Access Tokens"。
4. 输入 Token 名称（例如 "My API Token"）。
5. 选择过期时间（可选）。
6. 选择所需的权限范围（Scopes）。常用的 Scopes 包括：
  - api: 完全访问 API。
  - read_api: 只读访问 API。
  - read_repository: 读取仓库代码。
  - write_repository: 写入仓库代码。
  - read_user: 读取用户信息。
  - read_registry: 读取容器镜像仓库。
  - write_registry: 写入容器镜像仓库。
7. 点击 "Create personal access token" 按钮。
8. 复制生成的 Token。请注意，这个 Token 只会显示一次，请妥善保管。
在 API 请求中包含 Token

你有两种方式在 API 请求中包含 Token：
- HTTP Header: PRIVATE-TOKEN: <your_token>
- Query Parameter: https://gitlab.example.com/api/v4/projects?private_token=<your_token>
建议使用 HTTP Header 方式，因为它更安全。

3. 常用的 API 端点及示例

以下是一些常用的 GitLab API 端点及其示例：

用户（Users）
- 获取当前用户信息：
  
  GET /user
- 搜索用户：
  
  GET /users?search=john
- 创建用户（需要管理员权限）：
  
  POST /users { "email": "[email protected]", "password": "securepassword", "username": "newuser", "name": "New User" }
项目（Projects）
- 创建项目：
  
  POST /projects { "name": "My New Project", "description": "This is my new project.", "visibility": "private" // 或 "public", "internal" }
- 获取项目列表：
  
  GET /projects
- 获取单个项目信息：
  
  GET /projects/:id // :id 是项目的 ID 或 URL 编码的项目路径
- 更新项目：
  
  PUT /projects/:id { "description": "Updated description." }
- 删除项目：
  
  DELETE /projects/:id
分支（Branches）
- 获取分支列表：
  
  GET /projects/:id/repository/branches
- 创建分支：
  
  POST /projects/:id/repository/branches { "branch": "new-feature", "ref": "main" // 从哪个分支创建 }
- 删除分支：
  
  DELETE /projects/:id/repository/branches/:branch_name
合并请求（Merge Requests）
- 创建合并请求：
  
  POST /projects/:id/merge_requests { "source_branch": "new-feature", "target_branch": "main", "title": "My Merge Request", "description": "This is my merge request." }
- 获取合并请求列表：
  
  GET /projects/:id/merge_requests
- 接受合并请求：
  
  PUT /projects/:id/merge_requests/:merge_request_iid/merge
  其中:merge_request_iid是合并请求的内部id, 不是!xxx这种形式的
- 添加评论到合并请求：
  
  POST /projects/:id/merge_requests/:merge_request_iid/notes { "body": "This looks good!" }
议题（Issues）
- 创建议题：
  
  POST /projects/:id/issues { "title": "My Issue", "description": "This is my issue." }
- 获取议题列表：
  
  GET /projects/:id/issues
- 更新议题：
  
  PUT /projects/:id/issues/:issue_iid { "state_event": "close" // 或 "reopen" }
CI/CD流水线(Pipelines)
- 获取项目流水线
  GET /projects/:id/pipelines
- 触发流水线
  POST /projects/:id/pipeline?ref=<branch_or_tag>
- 取消或重试流水线
```
POST /projects/:id/pipelines/:pipeline_id/cancel
POST /projects/:id/pipelines/:pipeline_id/retry
```

4. 使用 Python 操作 GitLab API

python-gitlab 是一个流行的 Python 库，它封装了 GitLab API，使得操作 API 更加方便。

安装 python-gitlab 库

bash pip install python-gitlab
初始化 GitLab 客户端

```python
import gitlab

使用 Personal Access Token

gl = gitlab.Gitlab('https://gitlab.example.com', private_token='')

或者使用 OAuth2 Token

gl = gitlab.Gitlab('https://gitlab.example.com', oauth_token='')

也可以从配置文件中读取配置

gl = gitlab.Gitlab.from_config('gitlab', ['config.ini'])

```
执行 API 请求

```python

获取项目列表

projects = gl.projects.list(all=True) # 获取所有项目，包括归档的项目
for project in projects:
print(project.name)

创建项目

project = gl.projects.create({'name': 'My Python Project', 'visibility': 'private'})

获取项目

project = gl.projects.get(project.id)

更新项目

project.description = 'Updated description via Python.'
project.save()

删除项目

project.delete() # 谨慎操作

获取当前用户

user = gl.user
print(user.name)

搜索用户

users = gl.users.list(username='john')
for user in users:
print(user.email)
```
处理 API 响应

python-gitlab 会将 API 响应转换为 Python 对象，你可以像访问对象属性一样访问数据。
错误处理和异常捕获

python try: project = gl.projects.get(12345) # 不存在的项目 ID except gitlab.exceptions.GitlabGetError as e: print(f"Error: {e}") except Exception as e: print("An unexpected error")

python-gitlab 提供了各种异常类，例如 GitlabGetError、GitlabCreateError、GitlabUpdateError 等，你可以根据需要捕获特定的异常。

5. 实际案例

自动创建项目和初始化仓库

```python
import gitlab
import subprocess

gl = gitlab.Gitlab('https://gitlab.example.com', private_token='')

project_name = 'my-new-project'
project = gl.projects.create({'name': project_name, 'visibility': 'private'})

克隆仓库到本地

subprocess.run(['git', 'clone', project.ssh_url_to_repo])

进入仓库目录

subprocess.run(['cd', project_name], shell=True)

创建 README.md 文件

with open('README.md', 'w') as f:
f.write(f'# {project_name}\n\nThis is my new project.')

添加、提交和推送更改

subprocess.run(['git', 'add', '.'])
subprocess.run(['git', 'commit', '-m', 'Initial commit'])
subprocess.run(['git', 'push', '-u', 'origin', 'main'])
```
批量管理用户
读取csv文件, 批量创建用户

```python
import gitlab
import csv
gl = gitlab.Gitlab('https://gitlab.example.com', private_token='', api_version=4)

admin = gl.users.list(username='root')[0]
gl.auth_user = admin

with open('users.csv', 'r') as file:
reader = csv.DictReader(file)
for row in reader:
try:
user = gl.users.create(row)
print(f"User {row['username']} created successfully.")
except gitlab.exceptions.GitlabCreateError as e:
print("create user error")

```
根据代码提交自动创建合并请求

```python

假设你已经在本地修改了代码并提交到一个新分支

这个脚本可以自动创建合并请求

import gitlab
import subprocess

gl = gitlab.Gitlab('https://gitlab.example.com', private_token='')

获取当前分支

result = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], capture_output=True, text=True)
current_branch = result.stdout.strip()

获取项目 ID

project_id = 123 # 替换为你的项目 ID

创建合并请求

mr = gl.projects.get(project_id).mergerequests.create({
'source_branch': current_branch,
'target_branch': 'main',
'title': f'Merge {current_branch} into main',
'description': 'Automatically created merge request.'
})

print(f'Merge request created: {mr.web_url}')
```
监控 CI/CD 流水线状态并发送通知
可以使用gitlab的API获取流水线的状态, 然后根据状态发送通知(邮件, Slack, 企业微信等)
定期备份项目
可以使用GitLab API遍历所有项目, 然后使用git clone --mirror命令来备份项目代码, 以及项目的wiki.

6. 高级主题

GraphQL API

GitLab 还提供了 GraphQL API，它比 REST API 更灵活、更强大。你可以使用 GraphQL 查询语言来精确地指定你需要的数据，减少数据传输量。
Webhooks

Webhooks 允许你在 GitLab 中发生特定事件时（例如，代码推送、合并请求创建）自动触发外部服务。你可以配置 Webhooks 来将事件数据发送到你的服务器，然后执行自定义操作。

7. 总结与进阶资源

本教程介绍了 GitLab API 的基础知识，并通过示例和实际案例演示了如何使用 API 来自动化各种任务。掌握 GitLab API 将大大提高你的开发效率，并使你能够构建更强大的集成。

进阶资源：

GitLab API 官方文档：https://docs.gitlab.com/ee/api/
python-gitlab 文档：https://python-gitlab.readthedocs.io/
GitLab GraphQL API 文档： https://docs.gitlab.com/ee/api/graphql/
GitLab Webhooks 文档：https://docs.gitlab.com/ee/user/project/integrations/webhooks.html

希望这篇教程对你有所帮助！如果你有任何问题，请随时提问。

作者：admin

链接：https://hostlocvps.com/2025/03/13/gitlab-api-%e5%85%a5%e9%97%a8%e6%95%99%e7%a8%8b%ef%bc%9a%e4%bb%8e%e5%9f%ba%e7%a1%80%e5%88%b0%e5%ae%9e%e8%b7%b5/

文章版权归作者所有，未经允许请勿转载。

THE END

NFT、元宇宙与Web3：三者关系深度解析

<<上一篇

探索网络协议：Telnet 与 UDP 的特性分析

下一篇>>

GitLab API 入门教程：从基础到实践

GitLab API 入门教程：从基础到实践

使用 Personal Access Token

或者使用 OAuth2 Token

gl = gitlab.Gitlab('https://gitlab.example.com', oauth_token='')

也可以从配置文件中读取配置

gl = gitlab.Gitlab.from_config('gitlab', ['config.ini'])

获取项目列表

创建项目

获取项目

更新项目

删除项目

project.delete() # 谨慎操作

获取当前用户

搜索用户

克隆仓库到本地

进入仓库目录

创建 README.md 文件

添加、提交和推送更改

假设你已经在本地修改了代码并提交到一个新分支

这个脚本可以自动创建合并请求

获取当前分支

获取项目 ID

创建合并请求