CI Lint API

ネームスペースのCI/CD設定の検証

CI/CD YAML 設定が有効かどうかをチェックします。このエンドポイントは名前空間固有のコンテキストを持ちます。

POST /projects/:id/ci/lint
属性種類必須説明
content文字列です。はいCI/CD設定の内容。
dry_runbooleanなし パイプライン作成シミュレーションを実行するか、静的チェックのみを行います。デフォルト:false.
include_jobsbooleanなし静的検査またはパイプライン・シミュレーションに存在するジョブのリストを応答に含めるかどうか。デフォルト:false.
ref文字列です。なし dry_runtrue の場合、使用するブランチまたはタグを設定します。デフォルトはプロジェクトのデフォルトブランチです。

リクエストの例

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\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}'

レスポンスの例

  • 有効な設定:

     {
       "valid": true,
       "merged_yaml": "---\n:test_job:\n  :script: echo 1\n",
       "errors": [],
       "warnings": []
     }
    
  • 無効な設定です:

     {
       "valid": false,
       "merged_yaml": "---\n:test_job:\n  :script: echo 1\n",
       "errors": [
         "jobs config should contain at least one visible job"
       ],
       "warnings": []
     }
    

プロジェクトのCI設定を検証します。

プロジェクトの最新 (HEAD プロジェクトのデフォルトブランチ).gitlab-ci.yml の設定が有効かどうかをチェックします。このエンドポイントは、変数やローカルインクルードを含む、利用可能なすべての名前空間固有のデータを使用します。

GET /projects/:id/ci/lint
属性種類必須説明
dry_runbooleanなしパイプライン作成シミュレーションの実行、または静的チェックのみ。
include_jobsbooleanなし静的検査またはパイプライン・シミュレーションに存在するジョブのリストを応答に含めるかどうか。デフォルト:false.
ref文字列です。なし dry_runtrue の場合、使用するブランチまたはタグを設定します。デフォルトはプロジェクトのデフォルトブランチです。

リクエストの例

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

レスポンスの例

  • 有効な設定:
{
  "valid": true,
  "merged_yaml": "---\n:test_job:\n  :script: echo 1\n",
  "errors": [],
  "warnings": []
}
  • 無効な設定です:
{
  "valid": false,
  "merged_yaml": "---\n:test_job:\n  :script: echo 1\n",
  "errors": [
    "jobs config should contain at least one visible job"
  ],
  "warnings": []
}

CI YAML設定の検証(非推奨)

caution
このエンドポイントはGitLab 15.7で非推奨となり、16.0で削除されました。代わりに POST /projects/:id/ci/lintを使ってください。

CI/CD YAML 設定が有効かどうかをチェックします。このエンドポイントは CI/CD の基本的な設定構文を検証します。名前空間固有のコンテキストはありません。

インスタンスが新しいサインアップを許可している場合、このエンドポイントへのアクセスは認証を必要としません:

それ以外の場合は認証が必要です。

POST /ci/lint
属性種類必須説明
content文字列です。はいCI/CD設定の内容。
include_merged_yamlbooleanなし 拡張CI/CD設定を応答に含める必要がある場合。
include_jobsbooleanなしジョブのリストをレスポンスに含めるかどうか。デフォルト:false.
curl --header "Content-Type: application/json" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}'

GitLab CI/CD YAML 設定の内容を正確に貼り付けるようにしましょう。YAML はインデントやスペーシングにとても敏感だからです。

レスポンスの例

  • 有効な内容

     {
       "status": "valid",
       "errors": [],
       "warnings": []
     }
    
  • 警告付きの有効なコンテンツ

     {
       "status": "valid",
       "errors": [],
       "warnings": ["jobs:job may allow multiple pipelines to run for a single action due to
       `rules:when` clause with no `workflow:rules` - read more:
       https://docs.gitlab.com/ee/ci/troubleshooting.html#pipeline-warnings"]
     }
    
  • 無効なコンテンツです:

     {
       "status": "invalid",
       "errors": [
         "variables config should be a hash of key value pairs"
       ],
       "warnings": []
     }
    
  • コンテンツ属性がありません:

     {
       "error": "content is missing"
     }
    

YAML 展開

CI lint は設定の拡張バージョンを返します。include: localextends: キーワードは完全にはサポートされていません。

include_merged_yamlinclude_jobs を true にして CI Lint API に渡された.gitlab-ci.yml の内容例:

include:
  remote: 'https://example.com/remote.yaml'

test:
  stage: test
  script:
    - echo 1

https://example.com/remote.yaml の内容例:

another_test:
  stage: test
  script:
    - echo 2

応答例

{
  "status": "valid",
  "errors": [],
  "merged_yaml": "---\n:another_test:\n  :stage: test\n  :script: echo 2\n:test:\n  :stage: test\n  :script: echo 1\n",
  "jobs": [
    {
      "name":"test",
      "stage":"test",
      "before_script":[],
      "script":["echo 1"],
      "after_script":[],
      "tag_list":[],
      "environment":null,
      "when":"on_success",
      "allow_failure":false,
      "only":{
        "refs":["branches","tags"]
      },
      "except":null
    },
    {
      "name":"another_test",
      "stage":"test",
      "before_script":[],
      "script":["echo 2"],
      "after_script":[],
      "tag_list":[],
      "environment":null,
      "when":"on_success",
      "allow_failure":false,
      "only":{
        "refs":["branches","tags"]
      },
      "except":null
    }
  ]
}

jq を使用して YAML と JSON ペイロードを作成し処理します。

YAML 設定を CI Lint エンドポイントにPOST するには、適切にエスケープして 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 を使って GitLab API へPOST を一行のコマンドで送信します:

jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
| curl "https://gitlab.com/api/v4/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/*\n:deploy:\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でAPIにPOST
  4. レスポンスのフォーマット
jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
| curl "https://gitlab.com/api/v4/ci/lint?include_merged_yaml=true" \
--header 'Content-Type: application/json' --data @- \
| jq --raw-output '.merged_yaml | fromjson'