GitLab Stale 分支 API 脚本

如果你使用 GitLab 进行代码管理，你可能已经积累了很多没有被合并的旧分支。这些分支不仅对你的代码库造成冗余，而且会占用 GitLab 空间和资源。

这时候，你需要一个解决方案来自动检测和删除这些未被合并的分支。使用 GitLab 的 API，你可以轻松地编写一个脚本来执行这个任务。

API 认证

在开始编写脚本之前，你需要使用 GitLab 的 API 认证方式来进行 API 调用。API 认证方式包括：

• Private Token：Private Token 是一个能够代表用户进行 API 访问的唯一标识符。你可以通过 User Settings -> Access Tokens -> Add Token 创建一个 Access Token。

• OAuth2 Token：GitLab 支持使用 OAuth2 Token 进行 API 认证。

获取未合并的分支

首先，我们需要获取所有未合并的分支。我们可以使用以下 API 来获取所有未合并的分支：

GET /projects/:id/repository/branches?merged=false

其中，:id 指的是你的项目 ID。这个 API 将返回所有未被合并的分支列表。

以 Python 示例：

import requests

url = 'https://gitlab.com/api/v4/projects/1/repository/branches?merged=false'
headers = {'Private-Token': 'your_access_token'} # 替换为你的 Private-Token
response = requests.get(url, headers=headers)
print(response.json())

输出示例：

[
    {
        "name": "stale-branch-1",
        "commit": {
            "id": "3b3fc090b78c7eecd64a07a98a34614cb072aac9",
            "short_id": "3b3fc090",
            "title": "Initial commit",
            "author_name": "John Doe",
            "author_email": "johndoe@example.com",
            "committer_name": "John Doe",
            "committer_email": "johndoe@example.com",
            "created_at": "2021-07-01T00:00:00.000+00:00",
            "message": "Initial commit",
            "parent_ids": []
        }
    },
    {
        "name": "stale-branch-2",
        "commit": {
            "id": "f1c585841048a26921c900858cceba912970a773",
            "short_id": "f1c58584",
            "title": "Update README",
            "author_name": "John Doe",
            "author_email": "johndoe@example.com",
            "committer_name": "John Doe",
            "committer_email": "johndoe@example.com",
            "created_at": "2021-07-02T00:00:00.000+00:00",
            "message": "Update README",
            "parent_ids": [
                "3b3fc090b78c7eecd64a07a98a34614cb072aac9"
            ]
        }
    }
]

检查分支是否过期

接下来，我们需要检查这些未合并的分支是否过期。通常，一个过期的分支是指一个分支已经超过了一定的时间，并且没有被更新或者合并。我们可以设置一个时间阈值来决定一个分支是否过期。

打开 GitLab 网页版，进入相应的项目，点击 Settings -> Repository，可以设置 Default merge request approval rule，这里可以设置分支的生存期（可选），以及其它规则，推荐设置默认保护分支。

在这个例子中，我们假设一个分支被创建超过了 30 天并且没有被更新或合并，就被认为是过期的。我们可以通过以下代码来实现：

from datetime import datetime, timedelta

threshold_days = 30 # 设定时间阈值为 30 天

for branch in branches:
    date_str = branch['commit']['created_at'].split('T')[0] # 从 API 结果中提取提交时间
    commit_date = datetime.strptime(date_str, '%Y-%m-%d') # 将提交时间转换为 datetime 对象
    delta = datetime.today() - commit_date # 计算时间差
    if delta > timedelta(days=threshold_days):
        print(f'{branch["name"]} is stale.')
    else:
        print(f'{branch["name"]} is not stale.')

输出示例：

stale-branch-1 is stale.
stale-branch-2 is not stale.

删除过期分支

最后，我们可以删除所有过期的分支。我们可以使用以下 API 来删除分支：

DELETE /projects/:id/repository/branches/:branch_name

其中，:id 表示项目 ID，:branch_name 表示要删除的分支名称。

在此之前，需要在 GitLab 控制台创建合适的缺陷管理标签，在此标签下的分支将不会被清理，我们假设这些分支的标签为defect-management。

在 Python 中，删除过期分支的代码可以这样写：

for branch in branches:
    name = branch['name']
    date_str = branch['commit']['created_at'].split('T')[0]
    commit_date = datetime.strptime(date_str, '%Y-%m-%d')
    delta = datetime.today() - commit_date
    if delta > timedelta(days=threshold_days):
        # Check if the branch is labeled with "defect-management"
        labels_url = f'https://gitlab.com/api/v4/projects/1/repository/branches/{name}/labels'
        labels_resp = requests.get(labels_url, headers=headers)
        labels = labels_resp.json()
        if not any(label['name'] == 'defect-management' for label in labels):
            # Delete the stale branch if it's not labeled with "defect-management"
            delete_url = f'https://gitlab.com/api/v4/projects/1/repository/branches/{name}'
            delete_resp = requests.delete(delete_url, headers=headers)
            print(f'{name} is deleted. Response code: {delete_resp.status_code}')
        else:
            print(f'{name} is labeled with "defect-management", not deleted.')
    else:
        print(f'{name} is not stale.')

上述代码将检查所有过期分支，如果某个分支没有被标注为“defect-management”，则删除该分支。如果被标注为“defect-management”则不删除。

输出示例：

stale-branch-1 is stale.
stale-branch-1 is labeled with "defect-management", not deleted.
stale-branch-2 is not stale.

以上就是一个简单的使用 GitLab Stale 分支 API 的脚本，该脚本可以检查、删除过期分支，同时忽略某些被标注的分支不被清理。还可以加上邮件通知的功能，非常方便实用！