CI Lint API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

네임 스페이스에 대한 CI/CD 구성 유효성 검사

CI/CD YAML 구성이 유효한지 확인합니다. 이 엔드포인트는 네임스페이스별 컨텍스트를 가지고 있습니다. 

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\"}, \"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": [
    "작업 구성에는 최소한 하나의 가시적인 작업이 있어야 합니다"
  ],
  "warnings": []
}

프로젝트의 CI 구성 유효성 검사

특정 ref(기본값으로 프로젝트의 기본 브랜치의 HEAD)에서 프로젝트의 .gitlab-ci.yml 구성이 유효한지 확인합니다. 이 엔드포인트는 변수 및 지역 포함 등 네임스페이스별 데이터를 모두 사용합니다. 

GET /projects/:id/ci/lint
속성 형식 필수 설명
content_ref string 아니요 CI/CD 구성 내용을 가져옵니다. 커밋 SHA, 브랜치 또는 태그에서 기본값으로 프로젝트의 기본 브랜치의 HEAD SHA를 설정합니다.
dry_run_ref string 아니요 dry_run이 true일 때 사용할 가지 또는 태그 컨텍스트를 설정합니다. 설정하지 않은 경우 프로젝트의 기본 브랜치로 기본값을 설정합니다.
dry_run boolean 아니요 파이프라인 생성 시뮬레이션 실행 또는 정적 검사만 수행합니다.
include_jobs boolean 아니요 정적 검사 또는 파이프라인 시뮬레이션에서 존재하는 작업 디렉터리을 응답에 포함해야 하는지 여부입니다. 기본값: false.
ref string 아니요 (사용 중단됨) dry_run이 true일 때 CI/CD YAML 구성을 유효성 검사하는 데 사용할 가지 또는 태그 컨텍스트를 설정합니다. 설정되지 않은 경우 프로젝트의 기본 브랜치로 기본값을 설정합니다. 대신 dry_run_ref를 사용하세요.
sha string 아니요 (사용 중단됨) CI/CD 구성 내용을 가져옵니다. 커밋 SHA, 브랜치 또는 태그에서 기본값으로 프로젝트의 기본 브랜치의 HEAD SHA를 설정합니다. content_ref를 대신 사용하세요.

예시 요청: 

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": [
    "작업 구성에는 최소한 하나의 가시적인 작업이 있어야 합니다"
  ],
  "warnings": []
}

YAML 및 JSON 페이로드 생성 및 처리를 위한 jq 사용

CI Lint 엔드포인트에 YAML 구성을 POST하려면 제대로 이스케이프하고 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를 사용하여 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'