build:compile_site on GitLab Docs checks out MR head instead of merge commit
Background
When a Translation MR is created on the Gitlab Docs repo, there are errors in the Pipeline that sometimes occur. These errors are typically solved with a rebase. If the error is solved with a rebase, then they shouldn’t have occured in the first place, because the CI/CD runs on an ephemeral merge commit, not on the head commit of the MR. The ephemeral merge commit contains the same content as a rebased MR.
As a result of these errors, when reviewing a Translation MR with pipeline errors, the first step is to rebase it. While this is a solution to the problem, there are a few issues that result from this:
- The errors are false negatives that must be handled by an already stretched GitLab Translation MR Review team.
- The pipeline takes time to run, so re-runs delay the review.
- Rebasing Translation MRs is not an ideal solution since the translations are associated with a specific source file. Changes to source files during a rebase are not reflected in the target files, resulting in a mismatch.
This problem doesn’t just apply to Translation MRs, but any MR that makes changes to the GitLab Docs repo and runs the build process. Translation MRs are especially affected because it can take several days for the translations to come back, so the base commit of the MR will be several days old when the last commit of the MR is made.
Cause
Expected behavior: The downstream clone script should check out the merge commit SHA (using merge-requests/<IID>/merge) so the built content matches the upstream pipeline.
Actual behavior: The head commit of the MR is checked out during the script execution.
When the review-docs-deploy job in the https://gitlab.com/gitlab-org/gitlab repo triggers a downstream pipeline on docs-gitlab-com, the downstream build:compile_site job clones the GitLab repo at merge-requests/<IID>/head (the branch tip) rather than the merge commit that the upstream pipeline actually ran on so changes on the target branch do not appear in the deployment job which can cause the review app deployment to fail.
Example: Pipeline 2680170318, triggered by gitlab-org/gitlab MR !240760. The upstream pipeline (https://gitlab.com/gitlab-org/gitlab/-/pipelines/2676885024) ran on merge commit b13860ed (which has valid front matter, https://gitlab.com/gitlab-org/gitlab/-/blob/b13860ed4a79fbeff266e550e1fbec1ad8b5af54/doc-locale/ja-jp/operations/feature_flags.md), but the downstream job (https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/jobs/15368568340) checked out the branch tip 6f93c746 instead, which has a duplicate description key in doc-locale/ja-jp/operations/feature_flags.md, causing Hugo to fail with:
ERROR error building site: assemble: failed to create page from pageMetaSource /operations/feature_flags: mapping key "description" already defined at [4:1]
Change the go script to check out a merge commit, not the head commit of the MR.
In the cmd/internal/utils/product.go script used during make clone-docs-projects in docs-gitlab-com, when MERGE_REQUEST_IID is set, fetch and check out merge-requests/$MERGE_REQUEST_IID/merge instead of merge-requests/$MERGE_REQUEST_IID/head.