diff options
Diffstat (limited to 'doc/api/lint.md')
| -rw-r--r-- | doc/api/lint.md | 164 |
1 files changed, 7 insertions, 157 deletions
diff --git a/doc/api/lint.md b/doc/api/lint.md index 32318b9955d..7b288c34343 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -56,9 +56,12 @@ Example responses: ## Validate a project's CI configuration -Checks if a project's latest (`HEAD` of the project's default branch) -`.gitlab-ci.yml` configuration is valid. This endpoint uses all namespace -specific data available, including variables and local includes. +> `sha` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369212) in GitLab 16.5. + +Checks if a project’s `.gitlab-ci.yml` configuration in a given commit +(by default `HEAD` of the project’s default branch) is valid. This +endpoint uses all namespace specific data available, including variables +and local includes. ```plaintext GET /projects/:id/ci/lint @@ -69,6 +72,7 @@ GET /projects/:id/ci/lint | `dry_run` | boolean | No | Run pipeline creation simulation, or only do static check. | | `include_jobs` | boolean | No | If the list of jobs that would exist in a static check or pipeline simulation should be included in the response. Default: `false`. | | `ref` | string | No | When `dry_run` is `true`, sets the branch or tag to use. Defaults to the project's default branch when not set. | +| `sha` | string | No | The commit SHA of a branch or tag. Defaults to the SHA of the head of the project's default branch when not set. | Example request: @@ -102,160 +106,6 @@ Example responses: } ``` -<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> - -## Validate the CI YAML configuration (deprecated) - -WARNING: -This endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/381669) in GitLab 15.7 -and was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/403256) in 16.0. Use [`POST /projects/:id/ci/lint`](#validate-the-cicd-configuration-for-a-namespace) instead. - -Checks if CI/CD YAML configuration is valid. This endpoint validates basic CI/CD -configuration syntax. It doesn't have any namespace-specific context. - -Access to this endpoint does not require authentication when the instance -[allows new sign ups](../administration/settings/sign_up_restrictions.md#disable-new-sign-ups) -and: - -- Does not have an [allowlist or denylist](../administration/settings/sign_up_restrictions.md#allow-or-deny-sign-ups-using-specific-email-domains). -- Does not [require administrator approval for new sign ups](../administration/settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups). -- Does not have additional [sign up restrictions](../administration/settings/sign_up_restrictions.md). - -Otherwise, authentication is required. - -```plaintext -POST /ci/lint -``` - -| Attribute | Type | Required | Description | -|-----------------------|---------|----------|-------------| -| `content` | string | Yes | The CI/CD configuration content. | -| `include_merged_yaml` | boolean | No | If the [expanded CI/CD configuration](#yaml-expansion) should be included in the response. | -| `include_jobs` | boolean | No | If the list of jobs should be included in the response. Default: `false`. | - -```shell -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\"]}}"}' -``` - -Be sure to paste the exact contents of your GitLab CI/CD YAML configuration because YAML -is very sensitive about indentation and spacing. - -Example responses: - -- Valid content: - - ```json - { - "status": "valid", - "errors": [], - "warnings": [] - } - ``` - -- Valid content with warnings: - - ```json - { - "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"] - } - ``` - -- Invalid content: - - ```json - { - "status": "invalid", - "errors": [ - "variables config should be a hash of key value pairs" - ], - "warnings": [] - } - ``` - -- Without the content attribute: - - ```json - { - "error": "content is missing" - } - ``` - -### YAML expansion - -The CI lint returns an expanded version of the configuration. The expansion does not -work for CI configuration added with [`include: local`](../ci/yaml/index.md#includelocal), -and the [`extends:`](../ci/yaml/index.md#extends) keyword is [not fully supported](https://gitlab.com/gitlab-org/gitlab/-/issues/258843). - -Example contents of a `.gitlab-ci.yml` passed to the CI Lint API with -`include_merged_yaml` and `include_jobs` set as true: - -```yaml -include: - remote: 'https://example.com/remote.yaml' - -test: - stage: test - script: - - echo 1 -``` - -Example contents of `https://example.com/remote.yaml`: - -```yaml -another_test: - stage: test - script: - - echo 2 -``` - -Example response: - -```json -{ - "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 - } - ] -} -``` - -<!--- end_remove --> - ## Use jq to create and process YAML & JSON payloads To `POST` a YAML configuration to the CI Lint endpoint, it must be properly escaped and JSON encoded. |