Organizations

An organization is the top-level entity in the GitLab hierarchy. Each organization contains one or more top-level groups, and all of their subgroups and projects.

An organization acts as an administration layer above those groups, with a dedicated admin area where you can administer organization settings and manage users.

For more information about the state of organization development, see epic 9265.

Organizations are in closed beta, and available by invitation only to a limited set of beta participants. To request access, contact your GitLab account team.

Create an organization

Create an organization from an existing top-level group.

Prerequisites:

• The Owner role for the top-level group you start from, and for any other top-level group you want to include.

To create an organization from an existing top-level group:

1. In the top bar, select Search or go to and find your group. This group must be at the top level.
2. In the left sidebar, select Settings > General.
3. Expand Advanced.
4. In the Create an organization section, select Create organization.
5. In the Create your Organizations confirmation dialog, select the group you want to create an organization with, then select Continue.
6. Optional. If you have the Owner role for multiple top-level groups, in the Assign top-level groups confirmation dialog, drag those groups into the organization container. Groups you do not assign are not included. Select Continue.
7. In the Confirm your organization confirmation dialog, review the proposed structure.
8. Select Confirm.

After you confirm your organization structure:

• Your groups and projects transfer into the organization asynchronously.
• Users who are members of a transferred group or project become organization members.
• You receive an email when the transfer is ready. Larger groups take longer to transfer.
• Any user with the Owner role in all of the transferred top-level groups becomes an organization administrator.

You can change the organization name, URL, description, visibility, and avatar later from the organization admin area.

Go to your organization

If you are a member of one or more organizations, you can go to any of them from the Organizations page. To access an organization:

1. In the left sidebar, select Organizations.
2. From the list, select the organization you want to go to.

Organization URLs

An organization, and everything it contains, is addressed under /o/<organization-path>/. For example, https://gitlab.example.com/o/my-org/-/overview. Existing group and project URLs keep working.

Because o is a reserved path, no top-level group can use o as its path.

The default organization is an exception to this URL scheme. Its content stays on unscoped URLs.

The default organization

Every GitLab instance has one default organization. Every account starts in the default organization. The default organization cannot be deleted.

You leave the default organization when your top-level group moves into an organization of your own.

User types and permissions

An organization has two user types, organization administrator and organization regular user.

A user type describes a person’s relationship to the organization. For an organization regular user, group and project roles govern access to groups and projects. Organization administrators have full access to all groups and projects inside the organization.

The following table lists the actions available to each user type:

Only instance administrators can restore a deleted organization.

Organization administrators can also purchase organization-scoped products, such as the artifact registry. After you purchase a product, you can assign product-specific roles to organization users.

Group and project roles

Inside an organization, default roles still control access to groups and projects.

When a top-level group transfers into an organization, its group and project members become organization users. They keep their pre-existing roles and permissions.

Manage organization users

Use the organization admin area to add organization users, change their user type, and remove them.

Prerequisites:

• You must be an organization administrator.

View organization users

To view the users in your organization:

1. In the left sidebar, select Organizations.
2. From the dropdown list, select the organization you want to go to.
3. In the left sidebar, select Manage organization.
4. Select Organization overview > Users.

Add a user to an organization

To add a user to an organization:

1. In the left sidebar, select Organizations.
2. From the dropdown list, select the organization you want to go to.
3. In the left sidebar, select Manage organization.
4. Select Organization overview > Users.
5. Select Invite organization user.
6. In GitLab usernames, search for and select one or more users by username.
7. Under Organization user type, select one of the following:
   • Organization regular user: Grants a user access to groups and projects they are a member of.
   • Organization administrator: Grants access to all groups, projects, users, features, and the Organization Admin area.
8. Select Invite.

You can also add a user to an organization by adding them to a group or project in the organization.

Change a user’s type

To change whether a user is an organization regular user or an organization administrator:

1. In the left sidebar, select Organizations.
2. From the dropdown list, select the organization you want to go to.
3. In the left sidebar, select Manage organization.
4. Select Organization overview > Users.
5. Next to the user, select Edit.
6. Under Organization user type, select one of the following:
   • Organization regular user: Grants a user access to groups and projects they are a member of.
   • Organization administrator: Grants access to all groups, projects, users, features, and the Organization Admin area.
7. Select Save changes.

Remove a user from an organization

When you remove a user from an organization, they are also removed from all groups and projects in the organization.

To remove a user from an organization:

1. In the left sidebar, select Organizations.
2. From the dropdown list, select the organization you want to go to.
3. In the left sidebar, select Manage organization.
4. Select Organization overview > Users.
5. Next to the user, select the vertical ellipsis ( ) > Remove from organization.
6. In the confirmation dialog, select Remove.

Organization visibility

An organization is either public or private. Internal visibility is not available for organizations.

An organization cannot be more restrictive than the groups it contains. For example, you cannot make an organization private while it holds a public group.

Organization deletion

You can delete an organization only when it contains no groups and no projects, and it is not the default organization. GitLab soft-deletes the organization rather than removing it immediately. Only instance administrators can restore a deleted organization.

To delete an organization, you can also use the API.

Supported Markdown for organization description

The organization description field supports a limited subset of GitLab Flavored Markdown, including:

• Emphasis
• Links
• Superscripts / Subscripts