[Pages] Improve GitLab Pages onboarding

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

Problem to solve

The current Pages setup experience forces users through a configuration wizard workflow that creates unnecessary friction, especially for users who already have a configuration or prefer to manage their setup manually. Users need more flexibility in how they approach Pages configuration while still maintaining access to helpful guidance when needed.

Evidence

  • Issue raised by Suzanne Selhorn: #506397
  • Additional feedback from users indicating the wizard is "quite frustrating": #483652
  • Current behavior forces creation of redundant .gitlab-ci.yml files
  • Users cannot access basic information (like Pages URL) without completing the wizard
  • Particularly problematic when using project templates that already include Pages configuration

Proposal for Resolution 1

Improve the Pages setup experience by:

  1. Creating an intuitive empty state that clearly shows available options
  2. Allowing users to choose their preferred setup path:
    • Using a template-based approach
    • Manual configuration with example YAML snippets
    • Direct access to settings for existing configurations
  3. Showing relevant documentation and examples regardless of chosen path

Proposal for Resolution 2

A more straightforward approach: what if we simply make the Pages configuration stepper optional rather than mandatory?

Instead of implementing complex detection and merging logic, we could:

  1. Show an appropriate Pages dashboard that:
    • Displays No deployments yet if none exist
    • Shows deployment history and status if deployments have been attempted
    • Provides clear status information and troubleshooting guidance
  2. Provide a prominent but optional Configure with stepper button
  3. Allow users to freely access settings regardless of configuration status

This would immediately address the blocking issue users face when trying to view deployment status or diagnose problems, while still preserving the stepper as a helpful tool for those who need guidance.

Concerns

Janis detailed the following concern:

I think there is a misconception as to when the onboarding is currently shown: As soon as the first deployment is deployed, the onboarding screen is disabled. The onboarding screen only replaces the empty state. I agree that the information that there is no deployment yet would be helpful if we know there was an attempt at deploying one. But we can solve that by implementing phase 2, which is equally as much work as updating the UI to remove* the onboarding.

*yes, we'd be hiding the onboarding behind a button, but it would effectively be the same as removing it. What we had before the onboarding screen was exactly this: An empty state with a link to get started, which showed 70% fewer interactions.

As a compromise, how about adding a skip button to the onboarding instead? I've always opposed that because, similar to the above, I think it's a hack because we're not solving the root of the issue, which we should be doing, but if it means I don't have to spend my time arguing about it instead of fixing it, so be it.

Edited by 🤖 GitLab Bot 🤖