{{< 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_runtrue 时,设置分支或标签上下文以验证 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 中引入。
  • sharef 在极狐GitLab 16.10 中重命名为 content_refdry_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_runtrue 时,设置分支或标签上下文以验证 CI/CD YAML 配置。当未设置时,默认为项目的默认分支。
dry_run boolean 运行流水线创建模拟,或仅进行静态检查。
include_jobs boolean 是否在响应中包含静态检查或流水线模拟中将存在的作业列表。默认值:false
ref string (已弃用)当 dry_runtrue 时,设置分支或标签上下文以验证 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 编码。您可以使用 jqcurl 来转义并上传 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),并使用 curljq 在一个命令行中 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"

使用一个命令行,您可以:

  1. 转义 YAML
  2. 编码为 JSON
  3. 使用 curl 将其 POST 到 API
  4. 格式化响应
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'