[Documentation] Misleading statement about Review Apps automation and Auto DevOps prerequisites

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

[Documentation] Misleading statement about Review Apps automation and Auto DevOps prerequisites

Summary

The current introduction to Review Apps contains a potentially misleading statement about automation that could confuse new users about the infrastructure prerequisites required, even when using Auto DevOps.

Current Problem

Page: https://docs.gitlab.com/ci/review_apps/

Problematic statement:

"Review apps are temporary testing environments that are created automatically for each branch or merge request. You can preview and validate changes without needing to set up a local development environment."

Issue Description

The current wording creates confusion about what "automatically" means in the context of Review Apps, particularly given that GitLab offers both manual configuration and Auto DevOps approaches.

Manual Configuration Path

For manual setup, "automatically" is misleading because it requires:

• Custom .gitlab-ci.yml configuration
• Infrastructure setup (Kubernetes, cloud platforms, etc.)
• Deployment scripts and environment configuration
• Manual CI/CD pipeline design

Auto DevOps Path

Even with Auto DevOps (which does provide more automation), significant setup is still required:

• Kubernetes cluster preparation and connection to GitLab
• Cluster configuration (RBAC, Ingress controller, etc.)
• Auto DevOps feature activation
• Environment variables and authentication setup

Current Documentation Flow Issues

1. Immediate promise vs. reality gap: The introduction promises automation, but users quickly discover substantial prerequisites
2. Auto DevOps mention is buried: Auto DevOps is mentioned only briefly mid-document, despite being the primary path for true automation
3. Missing infrastructure emphasis: The document doesn't adequately emphasize upfront that Review Apps fundamentally require external infrastructure

Impact on Users

New users reading the introduction may expect Review Apps to work immediately, leading to:

• Confusion when discovering infrastructure requirements
• Frustration with complex setup procedures
• Potential abandonment of the feature due to unclear expectations
• Uncertainty about whether to use manual configuration vs. Auto DevOps

Suggested Solutions

Option 1: Restructured Introduction

"Review apps are temporary testing environments that can be created for each branch or merge request. Once configured, they allow you to preview and validate changes without setting up additional local development environments.

GitLab offers two approaches:

• Auto DevOps: Automated setup with minimal configuration (requires Kubernetes cluster)
• Manual configuration: Custom CI/CD pipeline setup for any infrastructure"

Option 2: Enhanced Current Introduction

"Review apps are temporary testing environments that are created automatically for each branch or merge request after initial setup. You can preview and validate changes without needing to set up a local development environment.

Quick start: If you have a Kubernetes cluster, Auto DevOps provides the fastest path to enabling Review Apps with minimal configuration."

Option 3: Prerequisites-First Approach

Add a prominent callout box before the current introduction:

💡 Before you start: Review Apps require either a Kubernetes cluster (for Auto DevOps) or custom infrastructure setup. Choose your approach below based on your available resources.

Recommended Changes

1. Clarify automation scope in the introduction
2. Promote Auto DevOps path earlier in the document for Kubernetes users
3. Add infrastructure decision tree to help users choose between approaches
4. Distinguish between "setup automation" vs "deployment automation"

Additional Context

• The Prerequisites section correctly mentions infrastructure requirements, but it's positioned after the potentially misleading introduction
• Auto DevOps significantly reduces configuration complexity but doesn't eliminate infrastructure requirements
• The current flow may discourage users who could benefit from Auto DevOps but assume all Review Apps require complex manual setup