Point the glab secure files examples at the job's instance

José M. Requena Plensrequested to merge
gitlab-community/gitlab-org/gitlab:jmrp-secure-files-glab-host into master

What does this MR do?

The two glab securefile download examples on Project-level secure files pass -R $CI_PROJECT_PATH. That value names the project but not the instance, so glab takes the instance from the job's Git remote, and only when that remote is on the host the job just logged in to with glab auth login --hostname $CI_SERVER_FQDN. In a default job, which clones the project from the instance's own URL, the examples work. In a job without a checkout, for example with GIT_STRATEGY: none, or in a job whose remote is on another host, for example because the runner clones from its clone_url or the instance sets a custom Git clone URL for HTTP(S), both commands send their request to gitlab.com instead of the instance that runs the job.

This MR changes both commands to -R $CI_PROJECT_URL. glab accepts a project URL for -R (its help says "The full URL or Git URL is also accepted.") and takes the instance from it, so both commands reach the job's own instance with or without a checkout. The glab auth login lines and the prose are unchanged. CI_PROJECT_URL is a predefined variable, so the two sentences that say the variables are predefined stay true.

The issue, and the suggested implementation plan in its comments, propose -R $CI_SERVER_FQDN/$CI_PROJECT_PATH. I tested that form too. It fixes the cases above on most instances, but not on two kinds:

  • An instance with a relative URL root. CI_SERVER_FQDN includes the relative URL root (config/settings.rb), and glab reads that extra segment as part of the project path. On an instance at https://example.test/gitlab, the commands ask for project gitlab/ns/proj, also in a default job, where the current commands work.
  • An instance whose host name has no dot, such as gitlab:8080, in a job without a checkout. glab reads the first segment of HOST/OWNER/REPO as a host only when it is gitlab.com, the default host, or a dotted host it has credentials for (internal/glrepo/repo.go). Otherwise it reads it as a group, and the request still goes to gitlab.com.

The glab documentation shows a third form for a manual login in CI, GITLAB_HOST=$CI_SERVER_FQDN glab -R $CI_PROJECT_PATH ... (Manual login), and the script GitLab generates for the release keyword sets GITLAB_HOST=$CI_SERVER_URL before it runs glab release create -R $CI_PROJECT_PATH (lib/gitlab/ci/build/releaser.rb). Both passed every case I tested. The project URL needs a recent glab: 1.81.0 drops the port from it, 1.86.0 reads a relative URL root as part of the project path, and 1.87.0 and 1.114.0 still do when the instance URL has both a port and a relative URL root. On such an instance that breaks a default job, where the current commands work. GITLAB_HOST=$CI_SERVER_URL passed every case in all four versions. I chose the project URL because the examples run cli:latest, which is 1.122.0 today and passed every case with it, and because it changes one value on each line and keeps every variable on the page predefined. I can switch to the GITLAB_HOST form if you prefer it.

How I tested it

I ran the page's own script lines, extracted from the file at master (709c08b88f7) and from this branch, in registry.gitlab.com/gitlab-org/cli:v1.122.0 (glab 1.122.0 (89d0008af), digest sha256:ca113f949a17d119984884b8937ae7aeff7b471ecaafc6ade015cc9c23707fc9, the image cli:latest resolves to today) with --network none. Each run sets the predefined variables of a job, runs glab auth login as the page writes it, then each download command, and reads the URL glab requested from the network error. A run passes when every download goes to <protocol>://<CI_SERVER_FQDN>/api/v4/projects/<CI_PROJECT_PATH>/secure_files.

Job CI_SERVER_FQDN master: -R $CI_PROJECT_PATH This MR: -R $CI_PROJECT_URL Issue: -R $CI_SERVER_FQDN/$CI_PROJECT_PATH
No checkout gitlab.example.test gitlab.com instance instance
No checkout, port and nested groups gitlab.example.test:8443 gitlab.com instance instance
Checkout, remote on the instance gitlab.example.test instance instance instance
Checkout, remote on another host (clone_url) gitlab.example.test gitlab.com instance instance
Checkout, relative URL root example.test/gitlab instance instance instance, project gitlab/ns/proj
No checkout, relative URL root example.test/gitlab gitlab.com instance instance, project gitlab/ns/proj
Checkout, host without a dot gitlab:8080 instance instance instance
No checkout, host without a dot gitlab:8080 gitlab.com instance gitlab.com, project gitlab:8080/ns/proj
No checkout, GitLab.com gitlab.com instance instance instance
Checkout, GitLab.com gitlab.com instance instance instance
Checkout, port, remote on the instance gitlab.example.test:8443 instance instance instance
Checkout, port and relative URL root example.test:8443/gitlab instance instance instance, project gitlab/ns/proj
Checkout, remote on a custom Git clone URL gitlab.example.test gitlab.com instance instance

For example, in the first row the master command requested https://gitlab.com/api/v4/projects/ns%2Fproj/secure_files and the command in this MR requested https://gitlab.example.test/api/v4/projects/ns%2Fproj/secure_files. The same runs in cli:v1.121.0 requested the same URLs in every row. The GITLAB_HOST=$CI_SERVER_FQDN form from the glab documentation and the GITLAB_HOST=$CI_SERVER_URL form of the release keyword sent every request to the instance, like this MR.

I also ran the current commands, this MR's form and the GITLAB_HOST=$CI_SERVER_URL form in the same thirteen cases with older images. In cli:v1.81.0 and cli:v1.86.0 this MR's form failed only where the current commands also fail. In cli:v1.87.0 and cli:v1.114.0 it failed only in the row with a port and a relative URL root, where the current commands work. The GITLAB_HOST=$CI_SERVER_URL form passed every case in all four.

Lint on this branch: markdownlint-cli2 0 issues, scripts/lint-doc.sh passed, and Vale reports the same six suggestions as on master, none on the changed lines. Both commit message linters pass.

Related issues

Closes #601971 (closed)

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

Merge request reports