diff options
-rw-r--r-- | .gitlab-ci.yml | 21 | ||||
-rw-r--r-- | doc/development/documentation/index.md | 38 | ||||
-rwxr-xr-x | scripts/trigger-build-docs | 10 |
3 files changed, 33 insertions, 36 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 45de5ce61c6..3424b44193c 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -255,10 +255,10 @@ package-and-qa: <<: *single-script-job-variables SCRIPT_NAME: trigger-build-docs environment: - name: review-docs/$CI_COMMIT_REF_SLUG + name: review-docs/$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID # DOCS_REVIEW_APPS_DOMAIN and DOCS_GITLAB_REPO_SUFFIX are CI variables # Discussion: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14236/diffs#note_40140693 - url: http://$CI_ENVIRONMENT_SLUG.$DOCS_REVIEW_APPS_DOMAIN/$DOCS_GITLAB_REPO_SUFFIX + url: http://docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID.$DOCS_REVIEW_APPS_DOMAIN/$DOCS_GITLAB_REPO_SUFFIX on_stop: review-docs-cleanup # Trigger a manual docs build in gitlab-docs only on non docs-only branches. @@ -271,8 +271,8 @@ review-docs-deploy-manual: - ./$SCRIPT_NAME deploy when: manual only: - - branches@gitlab-org/gitlab-ce - - branches@gitlab-org/gitlab-ee + - merge_requests@gitlab-org/gitlab-ce + - merge_requests@gitlab-org/gitlab-ee <<: *except-docs-and-qa # Always trigger a docs build in gitlab-docs only on docs-only branches. @@ -284,8 +284,11 @@ review-docs-deploy: - gem install gitlab --no-document - ./$SCRIPT_NAME deploy only: - - /(^docs[\/-].*|.*-docs$)/@gitlab-org/gitlab-ce - - /(^docs[\/-].*|.*-docs$)/@gitlab-org/gitlab-ee + refs: + - merge_requests@gitlab-org/gitlab-ce + - merge_requests@gitlab-org/gitlab-ee + variables: + - $CI_COMMIT_REF_NAME =~ /(^docs[\/-].*|.*-docs$)/ <<: *except-qa # Cleanup remote environment of gitlab-docs @@ -293,15 +296,15 @@ review-docs-cleanup: <<: *review-docs stage: post-cleanup environment: - name: review-docs/$CI_COMMIT_REF_SLUG + name: review-docs/$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID action: stop script: - gem install gitlab --no-document - ./$SCRIPT_NAME cleanup when: manual only: - - branches@gitlab-org/gitlab-ce - - branches@gitlab-org/gitlab-ee + - merge_requests@gitlab-org/gitlab-ce + - merge_requests@gitlab-org/gitlab-ee ## # Trigger a docker image build in CNG (Cloud Native GitLab) repository diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 828f9bfeec6..e9fad3a6f88 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -434,10 +434,10 @@ You will need to push a branch to those repositories, it doesn't work for forks. The `review-docs-deploy*` job will: 1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs) - project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`, + project named after the scheme: `docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID`, where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for - CE, etc. -1. Trigger a cross project pipeline and build the docs site with your changes + CE, etc., and the `CI_MERGE_REQUEST_IID` the number of the merge request. +1. Trigger a cross project pipeline and build the docs site with your changes. After a few minutes, the Review App will be deployed and you will be able to preview the changes. The docs URL can be found in two places: @@ -459,30 +459,25 @@ disk space. ### Troubleshooting review apps -In case the review app URL returns 404, follow these steps to debug: - -1. **Did you follow the URL from the merge request widget?** If yes, then check if - the link is the same as the one in the job output. -1. **Did you follow the URL from the job output?** If yes, then it means that - either the site is not yet deployed or something went wrong with the remote - pipeline. Give it a few minutes and it should appear online, otherwise you - can check the status of the remote pipeline from the link in the job output. - If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. +In case the review app URL returns 404, this means that either the site is not +yet deployed, or something went wrong with the remote pipeline. Give it a few +minutes and it should appear online, otherwise you can check the status of the +remote pipeline from the link in the merge request's job output. +If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. ### Technical aspects If you want to know the in-depth details, here's what's really happening: -1. You manually run the `review-docs-deploy` job in a CE/EE merge request. -1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs) +1. The `review-docs-deploy` job is run in a merge request. +1. The job executes the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs) script with the `deploy` flag, which in turn: - 1. Takes your branch name and applies the following: - - The slug of the branch name is used to avoid special characters since - ultimately this will be used by NGINX. - - The `preview-` prefix is added to avoid conflicts if there's a remote branch - with the same name that you created in the merge request. - - The final branch name is truncated to 42 characters to avoid filesystem - limitations with long branch names (> 63 chars). + 1. Forms the `gitlab-docs` branch name by applying the following: + - The `docs-preview-` prefix is added. + - The product slug is used to know the project the review app originated + from. + - The number of the merge request is added so that you can know by the + `gitlab-docs` branch name the merge requests it originated from. 1. The remote branch is then created if it doesn't exist (meaning you can re-run the manual job as many times as you want and this step will be skipped). 1. A new cross-project pipeline is triggered in the docs project. @@ -503,6 +498,7 @@ The following GitLab features are used among others: - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) - [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) +- [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md) ## Testing diff --git a/scripts/trigger-build-docs b/scripts/trigger-build-docs index dfc8ee6050a..5c55fd3ee31 100755 --- a/scripts/trigger-build-docs +++ b/scripts/trigger-build-docs @@ -16,14 +16,12 @@ end GITLAB_DOCS_REPO = 'gitlab-com/gitlab-docs'.freeze # -# Truncate the remote docs branch name otherwise we hit the filesystem -# limit and the directory name where NGINX serves the site won't match -# the branch name. +# This is the branch that will be created in the gitlab-docs project. +# Name it after the product we're previewing and the ID of the MR that +# kicked the review app. # def docs_branch - # The maximum string length a file can have on a filesystem (ext4) - # is 63 characters. CI_ENVIRONMENT_SLUG is limited to 24 characters. - ENV["CI_ENVIRONMENT_SLUG"] + "docs-preview-#{slug}-#{ENV["CI_MERGE_REQUEST_IID"]}" end # |