How organizations get created

Creating an organization happens through several independent paths today, and they do not all share the same gate. This page is an audit of every path, and what stands between an actor and a created organization. It documents the current state, not a target. Each path is expected to move into the organizations release process eventually, gradually, one at a time.

Creation paths

New organization form

The “New organization” form (Organizations::OrganizationsController#new), its navigation entry (Nav::NewDropdownHelper), and the “New” control on the organization list and the admin organization list (Organizations::OrganizationHelper#shared_organization_index_app_data) all check the organization_switching feature flag and the :create_organization ability.

Only the form enforces this, on the server, through authorize_create_organization!. The navigation entry and the “New” control are visibility only, not enforcement.

GraphQL mutation

The self-serve flow submits to Mutations::Organizations::Create. The mutation checks the :create_organization ability and the organization_switching feature flag. It then calls Organizations::CreateService, which checks the ability again. Anyone with GraphQL access and the ability can call this mutation directly, bypassing the self-serve flow entirely.

REST API

POST /organizations (lib/api/organizations.rb) checks the organization_switching feature flag, the :create_organization ability, and a rate limit, then calls Organizations::CreateService, which checks the ability again. This path is independent of the self-serve flow, and reachable with a personal access token.

Top-level group backfill and confirm (ops)

This path is the manual process for onboarding beta customers. It has two ChatOps-triggered steps, each an event-subscriber worker reacting to an actor-scoped ops feature flag:

• Organizations::RootGroupOrganizationBackfillWorker subscribes to root_group_organization_backfill. On enable, it creates the organization as unconfirmed and transfers the group into it.
• Organizations::ConfirmWorker subscribes to root_group_organization_confirm. On enable, it confirms the organization through Organizations::ConfirmService.

Both workers call their service with skip_authorization: true, bypassing the ability and every other gate on this page. Access is gated only by who can run ChatOps commands in production.

Create organization from group settings

This is the self-serve process for onboarding beta customers. It is gated behind the create_org_from_group_settings release flag which supports the group actor. This allows a group owner to create and confirm an organization for their TLG from Settings -> General -> Advanced. This is how the flow works:

1. Check if TLG has an unconfirmed non-default organization. If they do, then means their TLG has already been backfilled and we skip to step 3.
2. Make an API call to /groups/<group-path>/-/create_organization_from_group. This creates an organization as unconfirmed and transfers the group into it.
3. Select other TLGs the current user is an owner of to move into the organization.
4. Make a GraphQL call to Mutations::Organizations::Confirm. This transfers other TLGs that were selected and confirms the organization.
5. Confirming the organization triggers Organizations::ActivateService which transfers groups and projects into the organization and creates organization user records for all members of the groups/projects. Group members that are owners of all the TLGs become administrators of the organization.

The :create_organization ability

Several of the paths above also depend on the :create_organization ability, defined in app/policies/global_policy.rb. The ability has no role or ownership requirement. It resolves to true for any authenticated user when both of the following are true:

• The instance is GitLab.com. The ability is prevented outright on every other instance.
• The can_create_organization application setting is enabled. This setting defaults to true and has no other restriction.

In practice, the feature flag layer is the only thing narrowing who can create an organization today, not the ability.

Instance bootstrap

Two paths create an organization without an actor, and run only once, during instance setup:

• Gitlab::DatabaseImporters::DefaultOrganizationImporter creates the default organization every instance gets, from the db/fixtures/production/002_default_organization.rb fixture.
• Gitlab::DatabaseImporters::AdminOrganizationImporter creates a per-cell organization for the seeded administrator on any cell that does not own the default organization, from the db/fixtures/production/003_admin.rb fixture.

Neither path is reachable outside instance provisioning, and neither is part of the table above.