GitLab调用Group API无法列出组内所有项目的问题求助

排查优先级从高到低 #

• 接口路径调用错误
  你当前调用的/api/v4/groups/12345是查询分组基础信息的接口，返回体中内嵌的projects字段仅为当前分组下直属项目的预览数据，最多返回少量条目，并非分组下的全量项目列表，这是项目缺失的首要原因。查询分组下项目列表的正确接口路径为/api/v4/groups/12345/projects。
• 未处理分页逻辑
  GitLab所有列表类API默认开启分页，默认单页仅返回20条数据，单页最大支持返回100条。如果分组下项目总数超过单页上限，你未指定分页参数、也没有循环拉取所有分页的话，只会拿到第一页的项目，剩余页的项目会全部丢失。
• 未开启子组递归查询
  分组项目查询接口默认不会返回下级子组中的项目，如果你确认归属12345分组的缺失项目实际存放在该分组的子组下，必须显式传入include_subgroups=true参数，否则子组下的所有项目都不会出现在返回结果中。
• 默认过滤规则命中
  该接口默认会过滤掉已归档的项目，如果缺失项目属于归档状态，需要传入archived=both才能同时拉取归档和未归档的项目。你提到用同一个token单独调用Projects API可以正常查到缺失项目，可排除token权限不足的问题。

修复后可用脚本 #

先拉取总页数，再循环拉取所有分页的全量数据，避免漏数：

# 配置基础参数
export PRIVATE_TOKEN="你的私人访问令牌"
export GROUP_ID="12345"
export PER_PAGE=100 # 单页拉取上限，最大支持100

# 先请求第一页，从响应头获取总页数
TOTAL_PAGES=$(curl -sI --header "PRIVATE-TOKEN: ${PRIVATE_TOKEN}" \
"https://gitlab.com/api/v4/groups/${GROUP_ID}/projects?include_subgroups=true&archived=both&per_page=${PER_PAGE}" \
| grep -i x-total-pages | awk '{print $2}' | tr -d '\r\n')

# 初始化空文件，循环拉取所有页数据写入
> projects.txt
for ((page=1; page<=TOTAL_PAGES; page++)); do
  curl -s --header "PRIVATE-TOKEN: ${PRIVATE_TOKEN}" \
  "https://gitlab.com/api/v4/groups/${GROUP_ID}/projects?include_subgroups=true&archived=both&per_page=${PER_PAGE}&page=${page}" \
  | jq -c '.[]' >> projects.txt
done

脚本执行完成后，projects.txt中每一行对应一个项目的完整JSON数据，如果需要输出为完整JSON数组，可以调整jq处理逻辑增加数组包裹符即可。

校验方法 #

执行完成后可以通过wc -l projects.txt统计拉取到的项目总数，和GitLab Web端该分组（含子组）显示的项目总数做比对，也可以直接搜索之前缺失的项目ID/名称确认是否被正确拉取。

内容的提问来源于stack exchange，提问作者Luke