Documentation review apps contribute

GitLab team members can deploy a review app for merge requests with documentation changes. The review app lets you preview how your changes appear on the GitLab Docs site before merging.

Review app deployments are available for these projects:

Deploy a review app

You can deploy a review app by manually triggering the review-docs-deploy job in your merge request.

This job creates a preview of your documentation changes using the Hugo static site generation from the docs-gitlab-com project.

Prerequisites:

• You must have the Developer role for the project.

External contributors cannot run this job. If you’re an external contributor, ask a GitLab team member to run it for you.

To deploy a review app:

1. From your merge request, manually run the review-docs-deploy job. This job triggers a multi-project pipeline that builds and deploys the documentation site with your changes.
2. When the pipeline finishes, select View app to open the review app in your browser.

The review-docs-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-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 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.