GitLab CE 15.11.2：如何通过API将文件提交至LFS存储

一、REST API正确实现流程（先传LFS对象，再提交指针） #

你之前尝试的方法逻辑是对的，失败大概率是LFS指针格式错误或提交参数有误，以下是标准化步骤：

1. 上传文件到LFS对象存储
   调用POST /projects/{project_id}/lfs/objects端点，需携带文件、文件字节大小、文件的SHA256哈希（即LFS的OID）。
   示例请求（bash）：

curl --request POST \
  --header "PRIVATE-TOKEN: <你的访问令牌>" \
  --form "file=@/本地图片路径/photo.png" \
  --form "size=$(stat -c%s /本地图片路径/photo.png)" \
  --form "oid=$(sha256sum /本地图片路径/photo.png | cut -d' ' -f1)" \
  "https://你的GitLab实例地址/api/v4/projects/{project_id}/lfs/objects"

返回201 Created表示上传成功，200 OK则说明对象已存在。

2. 生成合规的LFS指针内容
   指针必须严格遵循LFS规范，格式如下（注意OID前缀sha256:不能省略）：

version https://git-lfs.github.com/spec/v1
oid sha256:<第一步获取的OID哈希值>
size <第一步获取的文件字节大小>

3. 提交LFS指针到仓库
   调用POST /projects/{project_id}/repository/commits端点，将指针内容作为文件内容提交，路径需与目标文件路径一致：
   示例请求（bash）：

curl --request POST \
  --header "PRIVATE-TOKEN: <你的访问令牌>" \
  --header "Content-Type: application/json" \
  --data '{
    "branch": "main",
    "commit_message": "通过API添加LFS图片",
    "actions": [
      {
        "action": "create",
        "file_path": "images/photo.png",
        "content": "version https://git-lfs.github.com/spec/v1\noid sha256:<OID哈希值>\nsize <文件字节大小>"
      }
    ]
  }' \
  "https://你的GitLab实例地址/api/v4/projects/{project_id}/repository/commits"

若更新已有文件，将action改为update即可。

二、GraphQL API实现方案（15.11.2版本支持） #

1. 上传LFS对象
   使用lfsObjectCreate mutation，文件内容需Base64编码：

mutation {
  lfsObjectCreate(
    input: {
      projectPath: "你的项目路径/如group/project",
      oid: "sha256:<OID哈希值>",
      size: <文件字节大小>,
      file: { content: "<图片文件的Base64编码内容>" }
    }
  ) {
    lfsObject {
      id
      oid
    }
    errors
  }
}

2. 提交LFS指针
   使用commitCreate mutation提交指针：

mutation {
  commitCreate(
    input: {
      projectPath: "你的项目路径/如group/project",
      branchName: "main",
      message: "通过GraphQL添加LFS图片",
      actions: [
        {
          action: CREATE,
          filePath: "images/photo.png",
          content: "version https://git-lfs.github.com/spec/v1\noid sha256:<OID哈希值>\nsize <文件字节大小>"
        }
      ]
    }
  ) {
    commit {
      id
      message
    }
    errors
  }
}

三、替代方案（API方案受阻时） #

1. GitLab CI流水线方案 #

提前在仓库中提交.gitattributes（用CLI执行git lfs track "*.png"后提交），然后编写CI任务自动处理：

upload-to-lfs:
  image: alpine/git:latest
  before_script:
    - apk add git-lfs
    - git lfs install
    - git config --global user.name "CI Bot"
    - git config --global user.email "ci-bot@yourdomain.com"
    - git clone https://oauth2:<你的访问令牌>@你的GitLab实例地址/你的项目路径.git .
    - git checkout main
  script:
    - # 从外部拉取图片，示例：curl https://外部图片地址/photo.png -o images/photo.png
    - git add images/photo.png
    - git commit -m "通过CI上传LFS图片"
    - git push origin main
  only:
    - triggers # 通过CI触发API启动该任务

2. 本地脚本方案 #

编写Shell/Python脚本结合Git LFS命令完成流程，示例Shell脚本：

#!/bin/bash

PROJECT_URL="https://oauth2:<你的访问令牌>@你的GitLab实例地址/你的项目路径.git"
BRANCH="main"
TARGET_PATH="images/photo.png"
LOCAL_FILE="/本地图片路径/photo.png"

# 临时仓库操作
TMP_DIR=$(mktemp -d)
cd $TMP_DIR

git init
git lfs install
git lfs track "*.png"
cp $LOCAL_FILE $TARGET_PATH

git config user.name "Script Bot"
git config user.email "script-bot@yourdomain.com"

git add .gitattributes $TARGET_PATH
git commit -m "通过脚本上传LFS图片"
git remote add origin $PROJECT_URL
git push origin $BRANCH

# 清理临时文件
cd ..
rm -rf $TMP_DIR

可定时运行或外部触发该脚本。

四、关键注意事项 #

• 需确保用户拥有仓库的开发者及以上权限
• 项目需开启LFS功能（项目设置→通用→可见性、项目功能、权限→启用LFS）
• LFS指针格式必须严格合规，OID前缀、大小与实际文件必须完全匹配

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