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:

Review apps deployments are available for these projects:

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 from docs-gitlab-com. This site replaced the previous site built with Nanoc.

To deploy a review app and preview changes:

  1. 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.
  2. 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:

  1. You manually run the review-docs-hugo-deploy job in a merge request.

  2. The job downloads (if outside of gitlab project) and runs the scripts/trigger-build.rb script with the docs-hugo deploy flag, which triggers a pipeline in the gitlab-org/technical-writing/docs-gitlab-com project.

    The DOCS_BRANCH environment variable determines which branch of the gitlab-org/technical-writing/docs-gitlab-com project to use. If not set, the main branch is used.

  3. 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.