## Summary This issue is to roll out [the feature](https://gitlab.com/gitlab-org/gitlab/-/issues/579942) on production, that is currently behind the `self_managed_welcome_onboarding` feature flag. This feature brings the "Create your first project" registration step to self-managed installations. After sign-in, admins with no groups are redirected to `/admin/registrations/groups/new` — a new onboarding page for first-time SM instance setup. This only applies to new installations (not upgrades) and only for the admin (root) user on first login. The feature is being delivered across 3 MRs: 1. !228898 — Feature flag and initial controller skeleton 2. !228899 — Service layer 3. !228900 — View layer Related epic: [Bring Welcome flow to self-managed instances](https://gitlab.com/groups/gitlab-org/-/epics/19488) ## Owners - Most appropriate Slack channel to reach out to: `#g_acquisition` - Best individual to reach out to: @bucoleary - Product Manager: @efergen - Engineering Manager: @ghosh-abhinaba ## Expectations ### What are we expecting to happen? When the feature flag is enabled on a self-managed instance: - The admin (root) user is redirected to `/admin/registrations/groups/new` after their first sign-in on a fresh installation - This redirect only occurs when no groups exist on the instance (new install, not an upgrade) - The page presents a "Create your first group" onboarding step - If the flag is disabled, the admin follows the normal post-sign-in flow with no redirect This is an instance-scoped flag — it applies to the entire SM instance when enabled. ### What can go wrong and how would we detect it? - **Redirect loop**: If the redirect logic has an edge case, admins could get stuck in a redirect loop after sign-in. We would detect this via an increase in 302 redirects in production logs. - **Blocking admin access**: If the feature flag gate or admin check has a bug, it could block admins from reaching the dashboard. Detected via 5xx errors or support reports. - **Upgrade scenario regression**: If `Group.any?` doesn't correctly detect existing groups on upgrades, existing instance admins could be incorrectly redirected. Detected via support tickets from upgrading customers. Note: Since this is a self-managed feature, GitLab.com dashboards are not the primary monitoring surface. SM telemetry is limited — we will rely on support channels and any available SM usage data. ## Rollout Steps Note: Please make sure to run the chatops commands in the Slack channel that gets impacted by the command. ### Rollout on non-production environments - Verify the MRs with the feature flag are merged to `master` and have been deployed to non-production environments with `/chatops gitlab run auto_deploy status <merge-commit-of-your-feature>` - [ ] Enable the feature globally on non-production environments with `/chatops gitlab run feature set self_managed_welcome_onboarding true --dev --pre --staging --staging-ref` - [ ] Verify that the feature works as expected. The best environment to validate the feature in is [`staging-canary`](https://about.gitlab.com/handbook/engineering/infrastructure/environments/#staging-canary) as this is the first environment deployed to. Make sure you are [configured to use canary](https://next.gitlab.com/). - [ ] If the feature flag causes end-to-end tests to fail, disable the feature flag on staging to avoid blocking [deployments](https://about.gitlab.com/handbook/engineering/deployments-and-releases/deployments/). **Note:** This feature targets self-managed instances specifically. Staging validation confirms the code paths don't break on GitLab.com, but full functional validation requires a GDK or omnibus environment with `GITLAB_SIMULATE_SAAS=0`. ### Before production rollout - [ ] If the change is significant and you wanted to announce in [#whats-happening-at-gitlab](https://gitlab.enterprise.slack.com/archives/C0259241C), it best to do it before rollout. ### Specific rollout on production For visibility, all `/chatops` commands that target production must be executed in the [`#production` Slack channel](https://gitlab.slack.com/archives/C101F3796) and cross-posted (with the command results) to the responsible team's Slack channel. - Ensure that the feature MRs have been deployed to both production and canary with `/chatops gitlab run auto_deploy status <merge-commit-of-your-feature>` - [ ] This is an **instance-scoped** flag (no actor). Enable globally: `/chatops gitlab run feature set self_managed_welcome_onboarding true` - [ ] Verify no adverse effects on GitLab.com (the flag should be a no-op on SaaS since the redirect logic targets SM admin root users with no groups). ### Preparation before global rollout - [ ] Set a milestone to this rollout issue to signal for enabling and removing the feature flag when it is stable. - [ ] Check if the feature flag change needs to be accompanied with a [change management issue](https://about.gitlab.com/handbook/engineering/infrastructure-platforms/change-management/#feature-flags-and-the-change-management-process). Cross link the issue here if it does. - [ ] Ensure that you or a representative in development can be available for at least 2 hours after feature flag updates in production. If a different developer will be covering, or an exception is needed, please inform the oncall SRE by using the `@sre-oncall` Slack alias. - [ ] Ensure that documentation exists for the feature, and the [version history text](https://docs.gitlab.com/development/documentation/feature_flags/#add-history-text) has been updated. - [ ] Ensure that any breaking changes have been announced following the [release post process](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations-removals-and-breaking-changes) to ensure GitLab customers are aware. - [ ] Notify the [`#support_gitlab-com` Slack channel](https://gitlab.slack.com/archives/C4XFU81LG) and your team channel ([more guidance when this is necessary in the dev docs](https://docs.gitlab.com/development/feature_flags/controls/#communicate-the-change)). ### Global rollout on production For visibility, all `/chatops` commands that target production must be executed in the [`#production` Slack channel](https://gitlab.slack.com/archives/C101F3796) and cross-posted (with the command results) to the responsible team's Slack channel. - [ ] Enable globally: `/chatops gitlab run feature set self_managed_welcome_onboarding true` - Between every step wait for at least 15 minutes and monitor the appropriate graphs on https://dashboards.gitlab.net. - [ ] After the feature has been 100% enabled, wait for [at least one day before releasing the feature](#release-the-feature). ### Release the feature After the feature has been [deemed stable](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#including-a-feature-behind-feature-flag-in-the-final-release), the [clean up](https://docs.gitlab.com/development/feature_flags/controls/#cleaning-up) should be done as soon as possible to permanently enable the feature and reduce complexity in the codebase. You can either [create a follow-up issue for Feature Flag Cleanup](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20Flag%20Cleanup) or use the checklist below in this same issue. - [ ] Create a merge request to remove the `self_managed_welcome_onboarding` feature flag. Ask for review/approval/merge as usual. The MR should include the following changes: - Remove all references to the feature flag from the codebase. - Remove the YAML definitions for the feature from the repository. - [ ] Ensure that the cleanup MR has been included in the release package. If the merge request was deployed before [the monthly release was tagged](https://about.gitlab.com/handbook/engineering/releases/#self-managed-releases-1), the feature can be officially announced in a release blog post: `/chatops gitlab run release check <merge-request-url> <milestone>` - [ ] Close [the feature issue](https://gitlab.com/gitlab-org/gitlab/-/issues/579942) to indicate the feature will be released in the current milestone. - [ ] Once the cleanup MR has been deployed to production, clean up the feature flag from all environments by running these chatops command in `#production` channel: `/chatops gitlab run feature delete self_managed_welcome_onboarding --dev --pre --staging --staging-ref --production` - [ ] Close this rollout issue. ## Rollback Steps - [ ] This feature can be disabled on production by running the following Chatops command: ``` /chatops gitlab run feature set self_managed_welcome_onboarding false ``` - [ ] Disable the feature flag on non-production environments: ``` /chatops gitlab run feature set self_managed_welcome_onboarding false --dev --pre --staging --staging-ref ``` - [ ] Delete feature flag from all environments: ``` /chatops gitlab run feature delete self_managed_welcome_onboarding --dev --pre --staging --staging-ref --production ```