CI Lint API

验证示例 CI/CD 配置#

检查示例 CI/CD YAML 配置是否有效。此端点验证项目上下文中的 CI/CD 配置，包括：

• 使用项目的 CI/CD 变量。
• 搜索项目文件中的 include:local 条目。

plaintext
POST /projects/:id/ci/lint

示例请求：

shell
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\"]}}"}'

示例响应：

• 有效配置：

  json
  1{
  2  "valid": true,
  3  "merged_yaml": "---\ntest_job:\n  script: echo 1\n",
  4  "errors": [],
  5  "warnings": [],
  6  "includes": []
  7}

• 无效配置：

  json
  1{
  2  "valid": false,
  3  "errors": [
  4    "jobs config should contain at least one visible job"
  5  ],
  6  "warnings": [],
  7  "merged_yaml": "---\n\".job\":\n  script:\n  - echo \"A hidden job\"\n",
  8  "includes": []
  9}

验证项目的 CI/CD 配置#

检查给定 ref（content_ref 参数，默认值为项目的默认分支的 HEAD）中的项目 .gitlab-ci.yml 配置是否有效。此端点验证 CI/CD 配置，包括：

• 使用项目的 CI/CD 变量。
• 搜索项目文件中的 include:local 条目。

plaintext
GET /projects/:id/ci/lint

示例请求：

shell
curl "https://gitlab.example.com/api/v4/projects/:id/ci/lint"

示例响应：

• 有效配置，include.yml 作为 包含文件 并且 include_jobs 设置为 true：

  json
  1{
  2  "valid": true,
  3  "errors": [],
  4  "warnings": [],
  5  "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",
  6  "includes": [
  7    {
  8      "type": "local",
  9      "location": "include.yml",
  10      "blob": "https://gitlab.example.com/test-group/test-project/-/blob/ef5014c045873c5c4ffeb7a2f5be021a1d3ed703/include.yml",
  11      "raw": "https://gitlab.example.com/test-group/test-project/-/raw/ef5014c045873c5c4ffeb7a2f5be021a1d3ed703/include.yml",
  12      "extra": {},
  13      "context_project": "test-group/test-project",
  14      "context_sha": "ef5014c045873c5c4ffeb7a2f5be021a1d3ed703"
  15    }
  16  ],
  17  "jobs": [
  18    {
  19      "name": "include-job",
  20      "stage": "test",
  21      "before_script": [],
  22      "script": [
  23        "echo \"An included job\""
  24      ],
  25      "after_script": [],
  26      "tag_list": [],
  27      "only": {
  28        "refs": [
  29          "branches",
  30          "tags"
  31        ]
  32      },
  33      "except": null,
  34      "environment": null,
  35      "when": "on_success",
  36      "allow_failure": false,
  37      "needs": null
  38    },
  39    {
  40      "name": "job",
  41      "stage": "test",
  42      "before_script": [],
  43      "script": [
  44        "echo \"A test job\""
  45      ],
  46      "after_script": [],
  47      "tag_list": [],
  48      "only": null,
  49      "except": null,
  50      "environment": null,
  51      "when": "on_success",
  52      "allow_failure": false,
  53      "needs": null
  54    }
  55  ]
  56}

• 无效配置：

  json
  1{
  2  "valid": false,
  3  "errors": [
  4    "jobs config should contain at least one visible job"
  5  ],
  6  "warnings": [],
  7  "merged_yaml": "---\n\".job\":\n  script:\n  - echo \"A hidden job\"\n",
  8  "includes": []
  9}

使用 jq 创建和处理 YAML & JSON 负载#

要将 YAML 配置 POST 到 CI Lint 端点，它必须被正确转义并进行 JSON 编码。您可以使用 jq 和 curl 来转义并上传 YAML 到极狐GitLab API。

为 JSON 编码转义 YAML#

要转义引号并以适合嵌入 JSON 负载的格式编码您的 YAML，您可以使用 jq。例如，创建一个名为 example-gitlab-ci.yml 的文件：

yaml
1.api_test:
2  rules:
3    - if: $CI_PIPELINE_SOURCE=="merge_request_event"
4      changes:
5        - src/api/*
6deploy:
7  extends:
8    - .api_test
9  rules:
10    - when: manual
11      allow_failure: true
12  script:
13    - echo "hello world"

接下来，使用 jq 将 YAML 文件转义并编码为 JSON：

shell
jq --raw-input --slurp < example-gitlab-ci.yml

要转义和编码输入的 YAML 文件（example-gitlab-ci.yml），并使用 curl 和 jq 在一个命令行中 POST 到极狐GitLab API：

shell
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 响应存储为文本文件并作为参数提供：

shell
jq --raw-output '.merged_yaml | fromjson' <your_input_here>

示例输入：

json
{"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"}

变为：

yaml
1.api_test:
2  rules:
3  - if: $CI_PIPELINE_SOURCE=="merge_request_event"
4    changes:
5    - src/api/*
6deploy:
7  rules:
8  - when: manual
9    allow_failure: true
10  extends:
11  - ".api_test"
12  script:
13  - echo "hello world"

使用一个命令行，您可以：

1. 转义 YAML
2. 编码为 JSON
3. 使用 curl 将其 POST 到 API
4. 格式化响应

shell
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'