Skip to content

Use less ambiguous parameter names in CI lint API

Manuel Grabowski requested to merge mg-improve-ci-lint-api-20240129 into master

What does this MR do and why?

This makes the parameter names for GET /projects/:id/ci/lint less confusing. Often ref and sha are used almost interchangeably, but in this specific context they served different functions that were not clear enough for many users.

Fixes #430322 (closed)

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

How to set up and validate locally

Set up a new project with these two files on the main branch:

.gitlab-ci.yml

include:
  - project: '$CI_PROJECT_PATH'
    ref: '$CI_COMMIT_REF_NAME'
    file: 'include.yml'

include.yml

test:
  script: exit 0

To verify the baseline, run these API requests against the current GitLab version, replacing 1234 with your project ID:

# This will fail ("Project `root/test` reference `` does not exist!") because without `dry_run` the `$CI_COMMIT_REF_NAME` variable is empty
curl -s --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "http://gdk.test:3000/api/v4/projects/1234/ci/lint"

# Add `dry_run` for the validation to succeed with `"valid":true,"errors":[],"warnings":[]` output
curl -s --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "http://gdk.test:3000/api/v4/projects/1234/ci/lint?dry_run=true"

# Explicitely specify "sha" (the content!) as "main" and it will still work (same as above)
curl -s --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "http://gdk.test:3000/api/v4/projects/1234/ci/lint?dry_run=true&sha=main"

# Also explicitely specify "ref" (the context!) as "main" and it will still work (same as both examples before)
curl -s --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "http://gdk.test:3000/api/v4/projects/1234/ci/lint?dry_run=true&sha=main&ref=main"

# Change "ref" from "main" to "wrong" and observe a validation error (Reference not found), because it would now try to include from a non-existing ref
curl -s --request GET --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "http://gdk.test:3000/api/v4/projects/1234/ci/lint?dry_run=true&sha=main&ref=wrong"

Now change to this branch and repeat the steps above – they will behave exactly the same as this must not be a breaking change.

Finally, repeat the steps but use content_ref instead of sha, and dry_run_ref instead of ref – again, the behavior will be identical (even if you mix and match).

Edited by Manuel Grabowski

Merge request reports