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: