如何动态生成GitLab API多文件提交适配可变变更文件的actions参数

核心逻辑是在npm run docs执行完成后，直接通过Git命令捕获工作区所有变更文件，自动映射为接口要求的actions结构，不需要预先定义文件列表。这种方式调用API生成的提交由GitLab服务端直接写入仓库，完全绕开本地GPG签名校验限制。

具体实现逻辑 #

• 执行完文档生成命令后，先通过git status --porcelain检测是否存在文件变更，无变更直接终止后续流程
• 按Git返回的文件状态标识，对应映射API支持的action类型：
  • 未跟踪新文件（状态标识??）对应create操作
  • 已修改文件（状态标识含M）对应update操作
  • 已删除文件（状态标识含D）对应delete操作
  • 重命名文件（状态标识R）对应move操作，额外提取原文件路径传入previous_path字段
  • 权限变更文件对应chmod操作，传入文件权限标识
• 用jq工具生成JSON结构，自动处理特殊字符转义，避免手动拼接JSON导致的格式错误
• 文件内容建议用base64编码传递，添加encoding: "base64"参数，兼容含特殊字符、大段文本的markdown文件，不会出现内容解析错误

可直接复用的CI脚本片段 #

# 执行文档生成命令
npm run docs

# 检测是否存在变更，无变更直接退出
if [[ -z $(git status --porcelain) ]]; then
  echo "No document changes detected, skip commit process"
  exit 0
fi

# 存储所有action配置
ACTION_ITEMS=()

# 遍历所有变更文件生成对应action配置
while IFS= read -r -d '' status file; do
  case "$status" in
    "D")
      # 处理删除文件
      ACTION_ITEMS+=("$(jq -n --arg fp "$file" '{"action": "delete", "file_path": $fp}')")
      ;;
    "M"|"??")
      # 处理修改/新增文件，base64编码文件内容避免转义问题
      file_content=$(base64 -w 0 "$file")
      action_type=$([[ "$status" == "??" ]] && echo "create" || echo "update")
      ACTION_ITEMS+=("$(jq -n \
        --arg fp "$file" \
        --arg at "$action_type" \
        --arg fc "$file_content" \
        '{"action": $at, "file_path": $fp, "content": $fc, "encoding": "base64"}')")
      ;;
  esac
done < <(git status --porcelain -z | awk -v RS='\0' '{
  # 提取文件状态和路径，处理不同位置的状态标识
  stat = substr($0, 1, 1)
  if (stat == " ") stat = substr($0, 2, 1)
  fpath = substr($0, 4)
  printf "%s\0%s\0", stat, fpath
}')

# 合并为合法的actions数组
ACTIONS_PAYLOAD=$(printf '%s\n' "${ACTION_ITEMS[@]}" | jq -s '.')

# 构造新分支名，避免冲突
TARGET_BRANCH="auto-docs-update-$(date +%Y%m%d%H%M%S)"

# 组装完整请求体
REQUEST_PAYLOAD=$(jq -n \
  --arg br "$TARGET_BRANCH" \
  --arg cm "chore: auto update generated docs" \
  --argjson acts "$ACTIONS_PAYLOAD" \
  '{"branch": $br, "commit_message": $cm, "actions": $acts}')

# 调用提交接口
curl --request POST \
  --header "PRIVATE-TOKEN: ${CI_PROJECT_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_PAYLOAD" \
  "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/repository/commits"

# 后续可直接调用MR创建接口，用上面生成的TARGET_BRANCH作为源分支创建MR即可

注意事项 #

• 不要手动拼接JSON字符串，所有JSON生成逻辑交给jq处理，自动适配引号、换行、特殊字符的转义规则，避免接口报格式错误
• CI环境需要提前配置具备仓库写权限的访问令牌，推荐使用项目级Access Token，比个人令牌权限更可控
• 如果文档生成逻辑会产生文件重命名、权限变更，只需要在状态判断的case分支里增加对应逻辑，映射到API要求的参数即可

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