diff options
author | Achilleas Pipinellis <axil@gitlab.com> | 2023-12-05 15:11:29 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2023-12-06 16:38:36 +0300 |
commit | bcd6397815cf4a2d7f3dcf1fd5b9c9c48c82b306 (patch) | |
tree | 97589e0bf67e76fc1565e5797a1fdf126301c5fc | |
parent | ee736525cabf43ab66ca6394804d607adb3a4570 (diff) |
Document clone_repositories Rake task
-rw-r--r-- | doc/raketasks.md | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/raketasks.md b/doc/raketasks.md index 6cef7f2a..c66a96c8 100644 --- a/doc/raketasks.md +++ b/doc/raketasks.md @@ -7,6 +7,59 @@ can see the list of rake tasks with: bundle exec rake -T ``` +## Clone the documentation repositories + +> **Note:** This is similar to +> [`make clone-all-docs-projects`](setup.md#clone-all-documentation-repositories). +> The Rake task is primarily used when building the site in CI/CD. + +The [`clone_repositories` rake task](../lib/tasks/build_site.rake) clones all the +[documentation repositories](architecture.md): + +```shell +bundle exec rake clone_repositories +``` + +The cloned locations are defined in [`nanoc.yaml` under `data_sources`](../nanoc.yaml). + +The task clones (with a depth of 1) either all the repositories or only one of them: + +- **All repositories:** When the task is run with no evironment variables set, + either locally or in a pipeline under `gitlab-docs`. +- **One repository:** When the task is run with some specific environment + variables, usually when a review app is triggered in one of the + [upstream projects](#usage-of-clone_repositories-in-an-upstream-review-app). + +Available environment variables: + +- `REMOVE_BEFORE_CLONE` or `CI`: if either of them is set (the value doesn't matter), + the repository to be cloned is removed if it already exists. This is always + 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. + +### Usage of `clone_repositories` in an upstream review app + +When you trigger a review app from an upstream project, only that project +is cloned and built. + +The following process describes how this works: + +1. You trigger a [review app](https://docs.gitlab.com/ee/development/documentation/review_apps.html) + 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`. + - `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` + Rake task with the environment variables above: + 1. Iterate over the five products. + 1. If `CI_PIPELINE_SOURCE` is set to `trigger`, **and** the `BRANCH_<project>` exists, + fetch the repository. Otherwise, skip it. + - `review`: deploys the artifacts (compiled site) from the previous job in a GCP bucket. + ## Generate the feature flag tables The [feature flag tables](https://docs.gitlab.com/ee/user/feature_flags.html) are generated @@ -22,6 +75,11 @@ Do this any time you want fresh data from your GitLab checkout. Any time you rebuild the site using `nanoc`, the feature flags tables are populated with data. +When this Rake task is run as part of an upstream review app, +`TOP_UPSTREAM_SOURCE_PROJECT` is set to the upstream project's path, and it's skipped if +it's not `'gitlab-org/gitlab'`. This is used in conjuction with +[`clone_repositories`](#usage-of-clone_repositories-in-an-upstream-review-app). + ## Clean up redirects The `docs:clean_redirects` rake task automates the removal of the expired redirect files, |