feat(api): add content_ref and dry_run_ref parameters to ProjectCiLintManager

Add support for the new GitLab API parameters for validating existing
CI/CD configurations:
- content_ref: specify the branch, tag, or SHA to validate
- dry_run_ref: set branch/tag context for dry run simulations

The deprecated 'ref' parameter is kept for backward compatibility.

Also update documentation with examples showing how to validate
CI configuration from specific branches and with dry run simulation.

Fixes python-gitlab#3260

Author: JohnVillalovos

docs/gl_objects/ci_lint.rst

@@ -46,6 +46,18 @@ Lint a project's CI configuration::
     assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
     print(lint_result.merged_yaml)    # Print the merged YAML file
 
+Lint a project's CI configuration from a specific branch or tag::
+
+    lint_result = project.ci_lint.get(content_ref="main")
+    assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
+    print(lint_result.merged_yaml)    # Print the merged YAML file
+
+Lint a project's CI configuration with dry run simulation::
+
+    lint_result = project.ci_lint.get(dry_run=True, dry_run_ref="develop")
+    assert lint_result.valid is True  # Test that the .gitlab-ci.yml is valid
+    print(lint_result.merged_yaml)    # Print the merged YAML file
+
 Lint a CI YAML configuration with a namespace::
 
     lint_result = project.ci_lint.create({"content": gitlab_ci_yml})

gitlab/v4/objects/ci_lint.py

@@ -51,7 +51,14 @@ class ProjectCiLintManager(
     _path = "/projects/{project_id}/ci/lint"
     _obj_cls = ProjectCiLint
     _from_parent_attrs = {"project_id": "id"}
-    _optional_get_attrs = ("dry_run", "include_jobs", "ref")
+    _optional_get_attrs = (
+        "content_ref",
+        "dry_run",
+        "dry_run_ref",
+        "include_jobs",
+        "ref",
+    )
+
     _create_attrs = RequiredOptional(
         required=("content",), optional=("dry_run", "include_jobs", "ref")
     )