Backend: CI Lint API GET parameters are confusing

Summary

The CI Lint API returns the content of the default branch in the merged_yaml when ref=<feature_branch>&dry_run=true is passed. This is expected behavior, as ref is for the context and not the content.

Steps to reproduce

• Configure a .gitlab-ci.yml in a project
• Create a feature branch
• Edit the .gitlab-ci.yml in the feature branch
• Call the Validate a project’s CI configuration api with ref=<feature_branch>&dry_run=true
• Inspect the merged_yaml in the response, this reflect the content of the default branch
  • This is because the sha parameter was not specified and thus the default branch was used

Proposal

To prevent any breaking change, new fields called dry_run_ref and content_ref will be added

Field	Definition
dry_run_ref	When dry_run is true, sets the branch or tag context to use to validate the CI/CD YAML configuration. Defaults to the project's default branch when not set.
content_ref	The ref from which the CI configuration is taken. Defaults to the SHA of the head of the project's default branch when not set.

Then, encouraging users via the docs to move over to use these new fields in the future with saying ref and sha are deprecated.

What is the current bug behavior?

The merged_yaml in the response contains the content of the default branch

What is the expected correct behavior?

The merged_yaml in the response contains the content of the specified branch

Relevant logs and/or screenshots

This bug happens on GitLab.com

Possible fixes