GitLab API创建项目报错：不是有效的HTTP Git仓库

DevOps 小满

2026-8-28

问题诱因

GitLab 14.9.2 版本存在API参数类型校验缺陷：该版本的JSON参数解析逻辑不会对字符串格式的布尔值做隐式转换，传入的字符串值"false"会被后端识别为布尔真值true，导致「从URL导入仓库」和「初始化README文件」两个互斥的创建流程同时触发，此时仓库校验逻辑不会实际发起Git拉取请求，直接返回导入地址无效的报错，和已知的参数关联问题完全吻合，本质是传参类型不对导致参数没有按预期生效。
带内嵌凭证的HTTPS地址解析bug：14.9版本对import_url字段的URL格式校验逻辑存在缺陷，如果访问令牌包含@、/、+、=这类特殊字符且没有做URL编码，校验逻辑解析地址时会把特殊字符后的内容截断，直接判定仓库地址非法，哪怕传入的是真实可访问的仓库地址也会返回相同报错。
整数类型参数格式错误：传入的namespace_id是字符串格式，14.x版本的GitLab API对整数类型参数做严格校验，格式不匹配时会触发参数解析链路的异常，连带导致import_url校验逻辑返回通用错误。

解决方法

先修正所有参数的类型，严格按照JSON原生类型传值：布尔类型的initialize_with_readme去掉引号传原生false，整数类型的namespace_id去掉引号传数值，不要用字符串格式传非字符串参数。修正后的请求示例：

curl --request POST --header "PRIVATE-TOKEN: <your-token>" \
     --header "Content-Type: application/json" --data '{
        "name": "new_project",
        "description": "New Project",
        "path": "new_project",
        "import_url": "https://user:<URL编码后的token>@gitlab.com/<实际项目路径>.git",
        "namespace_id": 42,
        "initialize_with_readme": false
     }' \
     --url 'https://gitlab.example.com/api/v4/projects/'

处理导入地址的凭证问题：如果访问令牌包含特殊字符，先对令牌做URL编码再拼接到import_url中；也可以不把凭证嵌在URL里，在请求体中额外加import_url_username和import_url_password两个字段传认证信息，能彻底规避URL内嵌凭证导致的解析错误。
临时规避版本bug：如果修正参数后仍然报错，可以直接从请求体中删掉initialize_with_readme参数不传递——只要请求中携带了import_url字段，该版本GitLab默认不会初始化README，不会触发两个流程的冲突，等项目导入完成后再手动添加README文件即可。
长期方案：该导入校验bug在14.10.3及之后的补丁版本中已经完成修复，长期使用建议升级到后续稳定版本，可避免大量API参数校验类的异常问题。

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