GitLab API

通过REST API与GitLab仓库交互。支持GitLab.com和自托管实例。

设置

存储您的GitLab个人访问令牌：

bash
mkdir -p ~/.config/gitlab
echo glpat-YOURTOKENHERE > ~/.config/gitlab/api_token

所需令牌范围： api 或 readapi + writerepository

获取令牌：

• - GitLab.com：https://gitlab.com/-/usersettings/personalaccesstokens
• 自托管：https://YOURGITLAB/~/-/usersettings/personalaccess_tokens

配置

默认实例：https://gitlab.com

对于自托管GitLab，创建配置文件：

bash
echo https://gitlab.example.com > ~/.config/gitlab/instance_url

常用操作

列出项目

bash
GITLABTOKEN=$(cat ~/.config/gitlab/apitoken)
GITLABURL=$(cat ~/.config/gitlab/instanceurl 2>/dev/null || echo https://gitlab.com)

curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \
$GITLABURL/api/v4/projects?owned=true&perpage=20

获取项目ID

项目通过ID或URL编码路径（namespace%2Fproject）进行标识。

bash

按路径

curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \
$GITLAB_URL/api/v4/projects/username%2Frepo

从响应中提取ID：jq .id

读取文件

bash
PROJECT_ID=12345
FILE_PATH=src/main.py
BRANCH=main

curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \
$GITLABURL/api/v4/projects/$PROJECTID/repository/files/${FILE_PATH}?ref=$BRANCH \
| jq -r .content | base64 -d

创建/更新文件

bash
PROJECT_ID=12345
FILEPATH=src/newfile.py
BRANCH=main
CONTENT=$(echo print(hello) | base64)

curl -X POST -H PRIVATE-TOKEN: $GITLAB_TOKEN \
-H Content-Type: application/json \
$GITLABURL/api/v4/projects/$PROJECTID/repository/files/${FILE_PATH} \
-d @- < {
branch: $BRANCH,
content: $CONTENT,
commit_message: 添加新文件,
encoding: base64
}
EOF

对于更新操作，使用 -X PUT 替代 -X POST。

删除文件

bash
curl -X DELETE -H PRIVATE-TOKEN: $GITLAB_TOKEN \
-H Content-Type: application/json \
$GITLABURL/api/v4/projects/$PROJECTID/repository/files/${FILE_PATH} \
-d {branch: main, commit_message: 删除文件}

列出目录中的文件

bash
curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \
$GITLABURL/api/v4/projects/$PROJECTID/repository/tree?path=src&ref=main

获取仓库内容（归档）

bash
curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \
$GITLABURL/api/v4/projects/$PROJECTID/repository/archive.tar.gz \
-o repo.tar.gz

列出分支

bash
curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \
$GITLABURL/api/v4/projects/$PROJECTID/repository/branches

创建分支

bash
curl -X POST -H PRIVATE-TOKEN: $GITLAB_TOKEN \
-H Content-Type: application/json \
$GITLABURL/api/v4/projects/$PROJECTID/repository/branches \
-d {branch: feature-xyz, ref: main}

辅助脚本

使用 scripts/gitlab_api.sh 进行常用操作：

bash

列出项目

./scripts/gitlab_api.sh list-projects

读取文件

./scripts/gitlab_api.sh read-file <项目ID> <文件路径> [分支]

写入文件

./scripts/gitlab_api.sh write-file <项目ID> <文件路径> <内容> <提交信息> [分支]

删除文件

./scripts/gitlab_api.sh delete-file <项目ID> <文件路径> <提交信息> [分支]

列出目录

./scripts/gitlab_api.sh list-dir <项目ID> <目录路径> [分支]

速率限制

• - GitLab.com：300次请求/分钟（已认证）
• 自托管：由管理员配置

API参考

完整API文档：https://docs.gitlab.com/ee/api/api_resources.html

关键端点：

• - 项目：/api/v4/projects
• 仓库文件：/api/v4/projects/:id/repository/files
• 仓库目录树：/api/v4/projects/:id/repository/tree
• 分支：/api/v4/projects/:id/repository/branches