{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: JihuLab.com, 私有化部署
{{< /details >}}
验证示例 CI/CD 配置
检查示例 CI/CD YAML 配置是否有效。此端点验证项目上下文中的 CI/CD 配置,包括:
- 使用项目的 CI/CD 变量。
- 搜索项目文件中的
include:local
条目。
POST /projects/:id/ci/lint
属性 | 类型 | 是否必需 | 描述 |
---|---|---|---|
content |
string | 是 | CI/CD 配置内容。 |
dry_run |
boolean | 否 | 运行 流水线创建模拟,或仅进行静态检查。默认值:false 。 |
include_jobs |
boolean | 否 | 是否在响应中包含静态检查或流水线模拟中将存在的作业列表。默认值:false 。 |
ref |
string | 否 | 当 dry_run 为 true 时,设置分支或标签上下文以验证 CI/CD YAML 配置。当未设置时,默认为项目的默认分支。 |
示例请求:
curl --header "Content-Type: application/json" "https://gitlab.example.com/api/v4/projects/:id/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"stages\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}'
示例响应:
-
有效配置:
{ "valid": true, "merged_yaml": "---\ntest_job:\n script: echo 1\n", "errors": [], "warnings": [], "includes": [] }
-
无效配置:
{ "valid": false, "errors": [ "jobs config should contain at least one visible job" ], "warnings": [], "merged_yaml": "---\n\".job\":\n script:\n - echo \"A hidden job\"\n", "includes": [] }
验证项目的 CI/CD 配置
{{< history >}}
-
sha
属性在极狐GitLab 16.5 中引入。 -
sha
和ref
在极狐GitLab 16.10 中重命名为content_ref
和dry_run_ref
。
{{< /history >}}
检查给定 ref(content_ref
参数,默认值为项目的默认分支的 HEAD
)中的项目 .gitlab-ci.yml
配置是否有效。此端点验证 CI/CD 配置,包括:
- 使用项目的 CI/CD 变量。
- 搜索项目文件中的
include:local
条目。
GET /projects/:id/ci/lint
属性 | 类型 | 是否必需 | 描述 |
---|---|---|---|
content_ref |
string | 否 | CI/CD 配置内容取自此提交 SHA、分支或标签。当未设置时,默认为项目的默认分支的头部 SHA。 |
dry_run_ref |
string | 否 | 当 dry_run 为 true 时,设置分支或标签上下文以验证 CI/CD YAML 配置。当未设置时,默认为项目的默认分支。 |
dry_run |
boolean | 否 | 运行流水线创建模拟,或仅进行静态检查。 |
include_jobs |
boolean | 否 | 是否在响应中包含静态检查或流水线模拟中将存在的作业列表。默认值:false 。 |
ref |
string | 否 | (已弃用)当 dry_run 为 true 时,设置分支或标签上下文以验证 CI/CD YAML 配置。当未设置时,默认为项目的默认分支。请改用 dry_run_ref 。 |
sha |
string | 否 | (已弃用)CI/CD 配置内容取自此提交 SHA、分支或标签。当未设置时,默认为项目的默认分支的头部 SHA。请改用 content_ref 。 |
示例请求:
curl "https://gitlab.example.com/api/v4/projects/:id/ci/lint"
示例响应:
-
有效配置,
include.yml
作为 包含文件 并且include_jobs
设置为true
:{ "valid": true, "errors": [], "warnings": [], "merged_yaml": "---\ninclude-job:\n script:\n - echo \"An included job\"\njob:\n rules:\n - if: \"$CI_COMMIT_BRANCH\"\n script:\n - echo \"A test job\"\n", "includes": [ { "type": "local", "location": "include.yml", "blob": "https://gitlab.example.com/test-group/test-project/-/blob/ef5014c045873c5c4ffeb7a2f5be021a1d3ed703/include.yml", "raw": "https://gitlab.example.com/test-group/test-project/-/raw/ef5014c045873c5c4ffeb7a2f5be021a1d3ed703/include.yml", "extra": {}, "context_project": "test-group/test-project", "context_sha": "ef5014c045873c5c4ffeb7a2f5be021a1d3ed703" } ], "jobs": [ { "name": "include-job", "stage": "test", "before_script": [], "script": [ "echo \"An included job\"" ], "after_script": [], "tag_list": [], "only": { "refs": [ "branches", "tags" ] }, "except": null, "environment": null, "when": "on_success", "allow_failure": false, "needs": null }, { "name": "job", "stage": "test", "before_script": [], "script": [ "echo \"A test job\"" ], "after_script": [], "tag_list": [], "only": null, "except": null, "environment": null, "when": "on_success", "allow_failure": false, "needs": null } ] }
-
无效配置:
{ "valid": false, "errors": [ "jobs config should contain at least one visible job" ], "warnings": [], "merged_yaml": "---\n\".job\":\n script:\n - echo \"A hidden job\"\n", "includes": [] }
使用 jq 创建和处理 YAML & JSON 负载
要将 YAML 配置 POST
到 CI Lint 端点,它必须被正确转义并进行 JSON 编码。您可以使用 jq
和 curl
来转义并上传 YAML 到极狐GitLab API。
为 JSON 编码转义 YAML
要转义引号并以适合嵌入 JSON 负载的格式编码您的 YAML,您可以使用 jq
。例如,创建一个名为 example-gitlab-ci.yml
的文件:
.api_test:
rules:
- if: $CI_PIPELINE_SOURCE=="merge_request_event"
changes:
- src/api/*
deploy:
extends:
- .api_test
rules:
- when: manual
allow_failure: true
script:
- echo "hello world"
接下来,使用 jq
将 YAML 文件转义并编码为 JSON:
jq --raw-input --slurp < example-gitlab-ci.yml
要转义和编码输入的 YAML 文件(example-gitlab-ci.yml
),并使用 curl
和 jq
在一个命令行中 POST
到极狐GitLab API:
jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
| curl "https://gitlab.com/api/v4/projects/:id/ci/lint?include_merged_yaml=true" \
--header 'Content-Type: application/json' \
--data @-
解析 CI Lint 响应
要重新格式化 CI Lint 响应,可以使用 jq
。您可以将 CI Lint 响应管道传递给 jq
,或将 API 响应存储为文本文件并作为参数提供:
jq --raw-output '.merged_yaml | fromjson' <your_input_here>
示例输入:
{"status":"valid","errors":[],"merged_yaml":"---\n.api_test:\n rules:\n - if: $CI_PIPELINE_SOURCE==\"merge_request_event\"\n changes:\n - src/api/*\ndeploy:\n rules:\n - when: manual\n allow_failure: true\n extends:\n - \".api_test\"\n script:\n - echo \"hello world\"\n"}
变为:
.api_test:
rules:
- if: $CI_PIPELINE_SOURCE=="merge_request_event"
changes:
- src/api/*
deploy:
rules:
- when: manual
allow_failure: true
extends:
- ".api_test"
script:
- echo "hello world"
使用一个命令行,您可以:
- 转义 YAML
- 编码为 JSON
- 使用 curl 将其 POST 到 API
- 格式化响应
jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
| curl "https://gitlab.com/api/v4/projects/:id/ci/lint?include_merged_yaml=true" \
--header 'Content-Type: application/json' --data @- \
| jq --raw-output '.merged_yaml | fromjson'