🎨 Design: Organization Experience Summary

Problem

This issue is intended to give an overview of the Organization experience.

Overview

See a complete overview: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/

Organizations on Cells 1.0 (FY24Q2-FY25Q4)

The Organization MVC for Cells 1.0 will contain the following functionality:

• Instance setting to allow the creation of multiple Organizations. This will be enabled by default on GitLab.com, and disabled for self-managed GitLab.
• Organizations for 1.0 will contain the minimal set of features required to implement isolation. Features that are present in top-level groups for SaaS, such as billing or enterprise users, will remain here.
• The only users who will need to have a role defined and be invited specifically to an Organization are it’s Owners. Typical end users will be invited at the group level, re-using the existing invitation workflows. The organization can be inferred by either the group or user.
• Admin overview of Organizations. All created Organizations are listed in the Admin Area section Organizations.
• All existing top-level Groups on GitLab.com are part of the default Organization.
• Organization Owner. The creation of an Organization appoints that User as the Organization Owner. Once established, the Organization Owner can appoint other Organization Owners.
• Organization Users. A User can only be part of one Organization for Cells 1.0. A new account needs to be created for each Organization a User wants to be part of. Users can only be deleted from an Organization, but not removed.
• Organization creation form. Containing the Organization name, ID, description, and avatar. Organization settings are editable by the Organization Owner.
• Setup flow. New Users are able to create new Organizations. They can also create new top-level Groups in an Organization.
• Private visibility. Initially, Organizations can only be private. Private Organizations can only be seen by the Users that are part of the private Organization. They can only contain private Groups and Projects. The only exception to this is the default Organization on the Primary Cell, which is public, and contains all currently existing Groups and Projects on GitLab.com.
• Organization settings page with the added ability to remove an Organization. Deletion of the default Organization is prevented.
• Groups. This includes the ability to create, edit, and delete Groups, as well as a Groups overview that can be accessed by the Organization Owner and Users.
• Projects. This includes the ability to create, edit, and delete Projects, as well as a Projects overview that can be accessed by the Organization Owner and Users.
• Personal Namespaces. Users get a personal Namespace in each Organization they are associated with.
• User Profile. Each User Profile will be scoped to the Organization.
• Isolation. Organizations themselves are not fully isolated, isolation is a result of being on a Secondary Cell. We aim to complete phase 1 of Organization isolation, with the goal to define sharding_key and desired_sharding_key rules.

Navigating

Within an organization	Possible Future State	Switching	Your work organizations	Admin navigating to organizations
	Note: this is just for visualization of a possible future and may evolve differently as features are added.	Switching organizations is being further investigated in #478260 Current design

Phases and ongoing work

• Switching will be disabled in 1.0 because users are limited to a single organization
• We are reevaluating the presentation of the switcher in #478260
• As features move down from admin to organization or up from groups/projects organization and admin navigation will evolve over time

Organization pages

Frontpage	Activity	Groups and projects

Phases and ongoing work

• We are evaluating how to incorporate admin views for groups and projects in #478262

Users

See additional info on organization users: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/organization-users/

Users can become an Organization member in the following way:

• Organization Owners create an account on behalf of a user, and then share it with the user.

Organization members can get access to Groups and Projects in an Organization as:

• A Group Member: this grants access to the Group and all its Projects, regardless of their visibility.
• A Project Member: this grants access to the Project, and limited access to parent Groups, regardless of their visibility.
• A Non-Member: this grants access to public and internal Groups and Projects of that Organization. To access a private Group or Project in an Organization, a user must become a member. Internal visibility will not be available for Organization in Cells 1.0.

Organization members can be managed in the following ways:

• As Enterprise Users, managed by the Organization. This includes control over their User account and the ability to block the User. In the context of Cells 1.0, Organization members will essentially function like Enterprise Users.
• As Non-Enterprise Users, managed by the default Organization. Non-Enterprise Users can be removed from an Organization, but the User keeps ownership of their User account. This will only be considered post Cells 1.0.

Enterprise Users are only available to Organizations with a Premium or Ultimate subscription. Organizations on the free tier will only be able to host Non-Enterprise Users.

Users	Leave confirmation	User creation form

Phases and ongoing work

• Added ability for users to leave an organization in #435936 and addressed sole owner edge case #441282 (closed)
  • In cells 1.0 users will be restricted from leaving
• Added the ability remove users in #435931
  • In cells 1.0 removing a user will delete their account
• Added the ability to assign additional owners in #441246 (closed)
• Added organization field to user creation form in #448811 (closed)
• Updated emails to include organization information in #465861 (closed)

Settings

See additional info regarding settings: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/organization-settings/

Organizations will provide value to users by improving the settings experience in the following ways:

• Expanding access to settings
  • Settings available only to self-managed become available to SaaS
  • Additional roles (Org Owner, Custom roles) will be able to manage settings
• Consolidating self-managed and SaaS experiences will reduce the use cases we need to manage and provide a more consistent experience.

To accomplish this:

• The long-term goal is to move almost all admin settings to the organization level and have only instance-specific (i.e. hardware) settings remain at the instance level.
• The length of time for this transition is likely to be long. To maintain the admin experience during this phase we will allow settings transitioned to the organization to continue being managed in the admin area wrapped in an organization selection. This will buy time, but the shorter the transition the better.

Organization settings general	Organization visibility	Setting migrated to organization level

Phases and ongoing work

• Added ability to set visibility of the organization during creation and via settings in #449028 (closed)
  • In Cells 1.0 visibility will be restricted to private
• Defined a migration strategy from admin to organizations in #419543
  • Self-managed will be restricted to a single organization Cells 1.0
• On-going exploration/demo of settings migration functionality in #478666 (closed)