diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/index.md | 38 |
1 files changed, 17 insertions, 21 deletions
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 |