feat: support validating CI lint results

2 files changed, 34 insertions, 3 deletions

diff --git a/docs/cli-examples.rst b/docs/cli-examples.rst
index 7f21f03..6c4364f 100644
--- a/docs/cli-examples.rst
+++ b/docs/cli-examples.rst
@@ -15,6 +15,9 @@ Lint a CI YAML configuration from a string:
 
    To see output, you will need to use the ``-v``/``--verbose`` flag.
 
+   To exit with non-zero on YAML lint failures instead, use the ``validate``
+   subcommand shown below.
+
 .. code-block:: console
 
    $ gitlab --verbose ci-lint create --content \
@@ -30,12 +33,24 @@ Lint a CI YAML configuration from a file (see :ref:`cli_from_files`):
 
    $ gitlab --verbose ci-lint create --content @.gitlab-ci.yml
 
+Validate a CI YAML configuration from a file (lints and exits with non-zero on failure):
+
+.. code-block:: console
+
+   $ gitlab ci-lint validate --content @.gitlab-ci.yml
+
 Lint a project's CI YAML configuration:
 
 .. code-block:: console
 
    $ gitlab --verbose project-ci-lint create --project-id group/my-project --content @.gitlab-ci.yml
 
+Validate a project's CI YAML configuration (lints and exits with non-zero on failure):
+
+.. code-block:: console
+
+   $ gitlab project-ci-lint validate --project-id group/my-project --content @.gitlab-ci.yml
+
 Lint a project's current CI YAML configuration:
 
 .. code-block:: console
diff --git a/docs/gl_objects/ci_lint.rst b/docs/gl_objects/ci_lint.rst
index 6533db3..ad2d875 100644
--- a/docs/gl_objects/ci_lint.rst
+++ b/docs/gl_objects/ci_lint.rst
@@ -19,7 +19,7 @@ Reference
 Examples
 ---------
 
-Validate a CI YAML configuration::
+Lint a CI YAML configuration::
 
     gitlab_ci_yml = """.api_test:
       rules:
@@ -40,14 +40,30 @@ Validate a CI YAML configuration::
     print(lint_result.status)  # Print the status of the CI YAML
     print(lint_result.merged_yaml)  # Print the merged YAML file
 
-Validate a project's CI configuration::
+Lint a project's CI configuration::
 
     lint_result = project.ci_lint.get()
     assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
     print(lint_result.merged_yaml)    # Print the merged YAML file
 
-Validate a CI YAML configuration with a namespace::
+Lint a CI YAML configuration with a namespace::
 
     lint_result = project.ci_lint.create({"content": gitlab_ci_yml})
     assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
     print(lint_result.merged_yaml)    # Print the merged YAML file
+
+Validate a CI YAML configuration (raises ``GitlabCiLintError`` on failures)::
+
+    # returns None
+    gl.ci_lint.validate({"content": gitlab_ci_yml})
+
+    # raises GitlabCiLintError
+    gl.ci_lint.validate({"content": "invalid"})
+
+Validate a CI YAML configuration with a namespace::
+
+    # returns None
+    project.ci_lint.validate({"content": gitlab_ci_yml})
+
+    # raises GitlabCiLintError
+    project.ci_lint.validate({"content": "invalid"})