Merge branch 'axil-docs-branch-variable' into 'main'

Document the use of the BRANCH_<slug> variable

See merge request https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/4542

Merged-by: Sarah German <sgerman@gitlab.com>
Reviewed-by: Achilleas Pipinellis <axil@gitlab.com>
Co-authored-by: Achilleas Pipinellis <axil@gitlab.com>

3 files changed, 57 insertions, 2 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 1a21c8b6..b771f94e 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -27,6 +27,16 @@ variables:
   MARKDOWNLINT2_VERSION: '0.12.1'  # Version also set in package.json
   RUBY_VERSION: '3.2.3'
   ASDF_VERSION: '0.14.0'
+  ## --------------------------------------------------------------------------
+  ## Uncomment any of the following variables if you want to build the site
+  ## using another upstream branch. See
+  ## https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clone-an-upstream-branch-other-than-the-default
+  ## --------------------------------------------------------------------------
+  # BRANCH_EE: <gitlab-branch>
+  # BRANCH_OMNIBUS: <omnibus-branch>
+  # BRANCH_RUNNER: <runner-branch>
+  # BRANCH_CHARTS: <charts-branch>
+  # BRANCH_OPERATOR: <operator-branch>
 
 #
 # workflow:rules to prevent duplicate pipelines when pushing to a branch with an open MR.
diff --git a/doc/development.md b/doc/development.md
index d9809d0a..d83ded88 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -196,6 +196,7 @@ To add an additional set of product documentation to <https://docs.gitlab.com> f
    branch at all, you can omit this and the default branch will be always pulled.
 
 1. Edit ['lib/edit_on_gitlab.rb'](../lib/edit_on_gitlab.rb) and add the product and its attributes to the `PRODUCT_REPOS` object, then add 1-2 test cases in [`spec/lib/helpers/edit_on_gitlab_spec.rb`](../spec/lib/helpers/edit_on_gitlab_spec.rb).
+1. Edit [`.gitlab-ci.yml`](../.gitlab-ci.yml) and add the new `BRANCH_<slug>` variable under `variables`. For example, if the slug is named `foo`, the variable should be named `BRANCH_FOO`.
 1. Edit [`.test.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/ci/test.gitlab-ci.yml) and add the new product to the following tests, following the same pattern as existing products:
 
    - `test_global_nav_links`
@@ -214,6 +215,7 @@ To add an additional set of product documentation to <https://docs.gitlab.com> f
 
    - Add the new product to the list in [`doc/index.md`](../doc/index.md).
    - Add the new product to the diagram in [`doc/architecture.md`](../doc/architecture.md).
+   - Add the new product environment variable (`BRANCH_<slug>`) in [`doc/raketasks.md`](../doc/raketasks.md#clone-an-upstream-branch-other-than-the-default).
 
 1. Add new whitespace test target to `markdownlint-whitespace-tests-gitlab` in `Makefile`.
 
diff --git a/doc/raketasks.md b/doc/raketasks.md
index c66a96c8..8a166dd4 100644
--- a/doc/raketasks.md
+++ b/doc/raketasks.md
@@ -37,6 +37,47 @@ Available environment variables:
   set in a pipeline since `CI` is set to `true` by default, and it makes sure we're
   not reusing an old version of the docs in case we land on a runner that already
   has a docs build.
+- `BRANCH_<slug>`: if you want to clone an upstream branch
+  [other than the default](#clone-an-upstream-branch-other-than-the-default).
+
+### Clone an upstream branch other than the default
+
+The
+[`clone_repositories` task](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fd64306b4ba4efd4081ac96e7cf69756fef2ce2f/lib/tasks/build_site.rake#L10)
+clones the
+[default branch](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fd64306b4ba4efd4081ac96e7cf69756fef2ce2f/lib/tasks/task_helpers.rb#L41)
+of an upstream project if the `BRANCH_<slug>` variable is not set.
+
+If you want to use another branch, you can use the `BRANCH_<slug>` environment
+variable for the following products:
+
+- `BRANCH_EE` for `gitlab-org/gitlab`
+- `BRANCH_OMNIBUS` for `gitlab-org/omnibus-gitlab`
+- `BRANCH_RUNNER` for `gitlab-org/gitlab-runner`
+- `BRANCH_CHARTS` for `gitlab-org/charts/gitlab`
+- `BRANCH_OPERATOR` for `gitlab-org/cloud-native/gitlab-operator`
+
+You can use those variables either locally or in a merge request:
+
+- The most common scenario is when you'd like to deploy a `gitlab-docs`
+  review app using an upstream branch that contains changes pertinent to that
+  `gitlab-docs` merge request:
+
+  1. In a `gitlab-docs` merge request, edit the `variables` section of
+     [`.gitlab-ci.yml`](../.gitlab-ci.yml), adding the `BRANCH_<slug>` variable
+     you want to pull the respective upstream branch for.
+  1. When you verify the merge request works the way you want, restore
+     `.gitlab-ci.yml` the way it was.
+
+- You can also use it locally by setting the variable before running the Rake task,
+  for example:
+
+  ```shell
+  BRANCH_EE=update-tier-badges bundle exec rake clone_repositories
+  ```
+
+  The above example fetches the default branches for all the upstream projects
+  except for `gitlab-org/gitlab`, which is set to `update-tier-badges`.
 
 ### Usage of `clone_repositories` in an upstream review app
 
@@ -49,8 +90,10 @@ The following process describes how this works:
    in an upstream project.
 1. The following variables are [set and passed](https://gitlab.com/gitlab-org/gitlab/-/blob/53233de16cafa6544ebe7bfbe41fd65e95645c8e/scripts/trigger-build.rb#L239-337)
    on the `gitlab-docs` pipeline:
-   - `BRANCH_<project>` is set to the upstream project's branch name, where
-     `<project>` is one of `ee`, `omnibus`, `runner`, `charts`, `operator`.
+   - `BRANCH_<slug>` is set to the upstream project's branch name, where
+     `<slug>` is one of `ee`, `omnibus`, `runner`, `charts`, `operator`. With this
+     variable set up, when the docs site is built, it fetches the
+     [respective upstream branch](#clone-an-upstream-branch-other-than-the-default).
    - `CI_PIPELINE_SOURCE` is set to `trigger`.
 1. A minimal pipeline is run in `gitlab-docs` with two jobs:
    - `compile_upstream_review_app`: builds the site by using the `clone_repositories`