Documentation review apps
If you're a GitLab team member and your merge request contains documentation changes, you can use a review app to preview how they would look if they were deployed to the GitLab Docs site.
Review apps are enabled for the following projects:
Alternatively, check the
gitlab-docs development guide
or the GDK documentation
to render and preview the documentation locally.
How to trigger a review app
If a merge request has documentation changes, use the
review-docs-deploy manual job
to deploy the documentation review app for your merge request.
review-docs-deploy* job triggers a cross project pipeline and builds the
docs site with your changes. When the pipeline finishes, the review app URL
appears in the merge request widget. Use it to navigate to your changes.
review-docs-cleanup job is triggered automatically on merge. This job deletes the review app.
You must have the Developer role in the project. Users without the Developer role, such as external contributors, cannot run the manual job. In that case, ask someone from the GitLab team to run the job.
If you want to know the in-depth details, here's what's really happening:
- You manually run the
review-docs-deployjob in a merge request.
- The job runs the
scripts/trigger-build.rbscript with the
docs deployflag, which triggers the "Triggered from
gitlab-org/gitlab'review-docs-deploy' job" pipeline trigger in the
gitlab-org/gitlab-docsproject for the
- The preview URL is shown both at the job output and in the merge request widget. You also get the link to the remote pipeline.
- In the
gitlab-org/gitlab-docsproject, the pipeline is created and it skips most test jobs to lower the build time.
- After the docs site is built, the HTML files are uploaded as artifacts to
a GCP bucket (see issue
gitlab-com/gl-infra/reliability#11021for the implementation details).
The following GitLab features are used among others:
Troubleshooting review apps
NoSuchKey The specified key does not exist
If you see the following message in a review app, either the site is not
yet deployed, or something went wrong with the downstream pipeline in
NoSuchKeyThe specified key does not exist.No such object: <URL>
In that case, you can:
- Wait a few minutes and the review app should appear online.
- Check the
review-docs-deployjob's log and verify the URL. If the URL shown in the merge request UI is different than the job log, try the one from the job log.
- Check the status of the remote pipeline from the link in the merge request's job output.
If the pipeline failed or got stuck, GitLab team members can ask for help in the
#docsinternal Slack channel. Contributors can ping a technical writer in the merge request.