API CI Lint

{{< details >}}

• Édition : Gratuite, GitLab Premium, GitLab Ultimate
• Offre : GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Utilisez cette API pour valider votre configuration GitLab CI/CD.

Ces endpoints utilisent du contenu YAML encodé en JSON. Dans certains cas, il peut être utile d'utiliser des outils tiers comme jq pour formater correctement votre contenu YAML avant d'effectuer une requête. Cela peut être utile si vous souhaitez conserver le format de votre configuration CI/CD.

Par exemple, la commande suivante utilise JQ pour échapper correctement un fichier YAML donné, l'encoder en JSON et effectuer une requête vers l'API.

jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
| curl --url "https://gitlab.com/api/v4/projects/:id/ci/lint?include_merged_yaml=true" \
--header 'Content-Type: application/json' \
--data @-

1. Créez un fichier YAML nommé example-gitlab-ci.yml :

   yamlCopy

   .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"
   

2. Pour échapper et encoder un fichier YAML d'entrée (example-gitlab-ci.yml), puis l'envoyer via POST à l'API GitLab, créez une commande sur une seule ligne combinant curl et jq :

   shellCopy

   jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
   | curl --url "https://gitlab.com/api/v4/projects/:id/ci/lint?include_merged_yaml=true" \
       --header 'Content-Type: application/json' \
       --data @-
   

Analyser les réponses de cette API {#parse-responses-from-this-api}

Pour reformater les réponses de l'API CI Lint, vous pouvez :

• Diriger la réponse CI Lint directement vers jq.

• Stocker la réponse de l'API dans un fichier texte et la fournir à jq comme argument, comme ceci :

  shellCopy

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

Par exemple, ce tableau JSON :

{"valid":"true","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"}

Une fois analysé et reformaté, le fichier YAML résultant contient :

.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"

Valider la configuration CI/CD {#validate-cicd-configuration}

Valide la configuration .gitlab-ci.yml pour un projet spécifié. Cet endpoint valide la configuration CI/CD dans le contexte du projet, notamment :

• L'utilisation des variables CI/CD du projet.
• La recherche des entrées include:local dans les fichiers du projet.

POST /projects/:id/ci/lint

Exemple de requête :

curl --request POST \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/:id/ci/lint" \
  --data @- <<'EOF'
{
  "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\"]
    }
  }"
}
EOF

Exemples de réponses :

• Configuration valide :

  jsonCopy

  {
    "valid": true,
    "merged_yaml": "---\ntest_job:\n  script: echo 1\n",
    "errors": [],
    "warnings": [],
    "includes": []
  }
  

• Configuration invalide :

  jsonCopy

  {
    "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": []
  }
  

Valider la configuration CI/CD existante {#validate-existing-cicd-configuration}

{{< history >}}

• L'attribut sha a été introduit dans GitLab 16.5.
• sha et ref ont été renommés en content_ref et dry_run_ref dans GitLab 16.10.

{{< /history >}}

Valide la configuration .gitlab-ci.yml existante pour un projet spécifié. Cet endpoint valide la configuration CI/CD dans le contexte du projet, notamment :

• L'utilisation des variables CI/CD du projet.
• La recherche des entrées include:local dans les fichiers du projet.

GET /projects/:id/ci/lint

Exemple de requête :

curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects/:id/ci/lint"

Exemples de réponses :

• Configuration valide, avec include.yml comme fichier inclus et include_jobs défini sur true :

  jsonCopy

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

• Configuration invalide :

  jsonCopy

  {
    "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": []
  }