Skip to content

External users

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

In cases where it is desired that a user has access only to some internal or private projects, there is the option of creating External Users. This feature may be useful when for example a contractor is working on a given project and should only have access to that project.

External users:

  • Cannot create project, groups, and snippets in their personal namespaces.
  • Can only create projects (including forks), subgroups, and snippets within top-level groups to which they are explicitly granted access.
  • Can access public groups and public projects.
  • Can only access projects and groups to which they are explicitly granted access. External users cannot access internal or private projects or groups that they are not granted access to.
  • Can only access public snippets.

Access can be granted by adding the user as member to the project or group. Like usual users, they receive a role for the project or group with all the abilities that are mentioned in the permissions table. For example, if an external user is added as Guest, and your project is internal or private, they do not have access to the code; you need to grant the external user access at the Reporter level or above if you want them to have access to the code. You should always take into account the project's visibility and permissions settings as well as the permission level of the user.

External users still count towards a license seat, unless the user has the Guest role in the Ultimate tier.

An administrator can flag a user as external by either of the following methods:

  • Through the API.
  • Using the GitLab UI:
    1. On the left sidebar, at the bottom, select Admin.
    2. On the left sidebar, select Overview > Users to create a new user or edit an existing one. There, you can find the option to flag the user as external.

Additionally, users can be set as external users using:

Make new users external by default

You can configure your instance to make all new users external by default. You can modify these user accounts later to remove the external designation.

When you configure this feature, you can also define a regular expression used to identify email addresses. New users with a matching email are excluded and not marked as an external user. This regular expression must:

  • Use the Ruby format.
  • Be convertible to JavaScript.
  • Have the ignore case flag set (/regex pattern/i).

For example:

  • \.int@example\.com$: Matches email addresses that end with .int@domain.com.
  • ^(?:(?!\.ext@example\.com).)*$\r?: Matches email address that don't include .ext@example.com.

Adding an regular expression can increase the risk of a regular expression denial of service (ReDoS) attack.

Prerequisites:

  • You must be an administrator for the GitLab Self-Managed instance.

To make new users external by default:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > General.
  3. Expand the Account and limit section.
  4. Select the Make new users external by default checkbox.
  5. Optional. In the Email exclusion pattern field, enter a regular expression.
  6. Select Save changes.