Documentation review apps
GitLab team members can deploy a review app for merge requests with documentation changes. The review app helps you preview what the changes would look like if they were deployed to either:
- The GitLab Docs site.
Review apps deployments are available for these projects:
- GitLab (configuration: https://gitlab.com/gitlab-org/gitlab/-/blob/b4f30955e41aeab862c59f7102529e1a5a2659d1/.gitlab/ci/docs.gitlab-ci.yml#L1-40)
- Omnibus GitLab (configuration: https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/bae935d36ea9296941c20233b637d780847c443a/gitlab-ci-config/gitlab-com.yml#L304-328)
- GitLab Runner (configuration: https://gitlab.com/gitlab-org/gitlab-runner/-/blob/69d2416333df4712cbd95d90214b10f100183df3/.gitlab/ci/docs.gitlab-ci.yml#L64-110)
- GitLab Charts (configuration: https://gitlab.com/gitlab-org/charts/gitlab/-/blob/8222a7c3cf28d8ad3f454784a04cad8921b6638b/.gitlab/ci/review-docs.yml#L2-49)
- GitLab Operator (configuration: https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/56200465a5c8f8857f3aef2c309bdf2ca9e4b672/.gitlab-ci.yml#L210-257)
Deploy a review app and preview changes
Prerequisites:
- You must have the Developer role for the project. External contributors cannot run these jobs and should ask a GitLab team member to run the jobs for them.
For merge requests with documentation changes, you can manually trigger the following deploy job:
review-docs-hugo-deploy
: Creates a review app to preview your documentation changes using the Hugo static site generation fromdocs-gitlab-com
. This site replaced the previous site built with Nanoc.
To deploy a review app and preview changes:
- Manually run either (or both) of these jobs. These jobs trigger a multi project pipelines, build the documentation site with your changes, and deploy a site with your changes.
- When the pipeline finishes, select View app on either deployment to open a browser and review the changes introduced by the merge request.
The review-docs-hugo-cleanup
job is triggered automatically on merge. This job deletes
the review app.
How documentation review apps work
Documentation review apps follow this process:
You manually run the
review-docs-hugo-deploy
job in a merge request.The job downloads (if outside of
gitlab
project) and runs thescripts/trigger-build.rb
script with thedocs-hugo deploy
flag, which triggers a pipeline in thegitlab-org/technical-writing/docs-gitlab-com
project.The
DOCS_BRANCH
environment variable determines which branch of thegitlab-org/technical-writing/docs-gitlab-com
project to use. If not set, themain
branch is used.After the documentation preview site is built, it is deployed in parallel to other review apps.
Troubleshooting
When working with review apps, you might encounter the following issues.
Error: 401 Unauthorized
in documentation review app deployment jobs
You might get an error in a review app deployment job that states:
Server responded with code 401, message: 401 Unauthorized.
This issue occurs when the DOCS_HUGO_PROJECT_API_TOKEN
has either:
- Expired or been revoked and must be regenerated.
- Been recreated, but the CI/CD variable in the projects that use it wasn’t updated.
These conditions result in the deployment job for the documentation review app being unable to query the downstream project for the status of the downstream pipeline.
To resolve this issue, contact the Technical Writing team. For more information on documentation review app tokens, see GitLab docs site maintenance.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support