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.

Merge requests with documentation changes have the following jobs available:

  • review-docs-deploy, which uses Nanoc static-site generation using gitlab-docs.
  • review-docs-hugo-deploy: Optional. This review app is only for testing the Hugo static site generation from gitlab-docs-hugo, which is still in development.

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-cleanup and review-docs-hugo-cleanup jobs are triggered automatically on merge. These job delete the review app.

How documentation review apps work

Documentation review apps follow this process:

  1. You manually run the review-docs-deploy or 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 either:

    • The docs deploy flag, which triggers a pipeline in the gitlab-org/gitlab-docs project.
    • The docs-hugo deploy flag, which triggers a pipeline in the gitlab-org/technical-writing-group/gitlab-docs-hugo project.

    The DOCS_BRANCH environment variable determines which branch of either the gitlab-org/gitlab-docs project or the gitlab-org/technical-writing-group/gitlab-docs-hugo project are used. If not set, the main branch is used.

  3. After the documentation preview site is built:

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_PROJECT_API_TOKEN (or 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.