The ultimate guide to least privilege access with GitLab

The principle of least privilege (PoLP) is a concept in which a user's access rights should be limited to the bare minimum needed for them to complete the tasks required within their respective roles. By implementing PoLP you can enhance your organization's security posture, complementing zero trust, in the following ways:

• Reduction of attack surface: If credentials are compromised, the breach will be limited to only the paths where the compromised account has access.
• Protection against human error: Users will not be able to perform actions that are not required for their role.
• Adherence to compliance: Separation of duties and least privilege best practices are required for several compliance mandates such as SOC2 and HIPAA.
• Reduced system downtime: By preventing everyone from accessing critical parts of the software development lifecycle (SDLC), there is less likelihood of downtime.

GitLab provides a variety of different features that allow you to customize the actions a user can perform which assist in the achievement of PoLP. These features include:

• Custom roles and granular security permissions: Allows creation of roles with permissions that are specific to particular functions required by the organization.
• Security policies: Allows policies to be created that prevent insecure code from being merged into production branches without approval, and run security scanners regardless of your pipeline definition.
• Branch protections and Code Owners: Imposes further restrictions on certain branches to control permissions such as who can merge, push, etc. to defined branches.
• Compliance pipelines and frameworks: Identifies that your project has certain compliance requirements or needs additional oversight, enforcing a pipeline configuration to the projects on which it is applied.

In this blog post, you'll learn each of the features mentioned, how they improve your organization's security posture, as well as how to implement them.

Watch my video, which introduces you to achieving PoLP with GitLab:

Custom roles and granular security permissions

GitLab allows you to create custom roles, which apply additional permissions to base roles to meet the security needs of your organization. The available base roles are as follows:

• Guest
• Reporter
• Developer
• Maintainer
• Owner

Each base role applies a particular set of permissions to a user. Base roles apply different permissions for group members, project members, and in project features. For example, the table below shows which roles can view the project dependency list:

Base role	Can view project dependency list
Guest	❌
Reporter	❌
Developer	✅
Maintainer	✅
Owner	✅

The dependency list also known as a software bill of materials (SBOM), displays your project's dependencies and key details about those dependencies. It makes sense that only those actively working on a project should be able to see what dependencies are present to limit any exploitation of your application using its dependencies.

However, there are cases in which a Guest may need to see the SBOM to assist the organization in achieving compliance. By using custom roles, a new role can be created with all the limited permissions of the Guest role, and additionally, the ability to view the project dependency list can be added. Therefore, we have a Guest assisting us with compliance with the least privileged access required for their job.

Watch my video on custom roles and granular security permissions with GitLab:

Granular permissions

As of the GitLab 16.8 release, the following granular permissions can be added to any base role:

• Viewing project code
• Viewing vulnerability reports
• Changing the status of vulnerabilities
• Viewing SBOMs
• Approving merge requests
• Managing project/group access tokens
• Adding/removing group members
• Archiving/unarchiving/removing projects
• Admin Terraform state

We will continue to add more granular permissions with each GitLab release. You can learn more about our roadmap for this feature by referring to the Granular Security Permissions Epic and provide feedback in the customer feedback Issue. You also have the ability to contribute to GitLab and develop your own granular permissions.

Implementation prerequisites

The requirements for implementing custom roles are as follows:

• Owner role in the top-level group in which you are creating the custom role
• Administrator for the self-managed instance in which you are creating the custom role
• GitLab Ultimate tier in the top-level group
• A personal access token with the API scope

To see custom roles in action requires:

• a private project within the top-level group or its subgroups
• a guest user within the private project

When you enable a custom role for a user with the Guest role, that user has access to elevated permissions, and therefore:

• is considered a billable user on self-managed GitLab
• uses a seat on GitLab.com

Creating the custom role with granular permissions

Now that you know the benefits of implementing custom roles with granular permissions, let's implement them within our GitLab instance:

1. On the left sidebar, select Search or go to.
   • In GitLab SaaS find and select the top-level group in which you want to create a custom role.
   • In GitLab Self-Managed find and select Admin Area.
2. Select Settings > Roles and Permissions.
   • In GitLab Self-Managed use the top dropdown list to find and select the top-level group in which you want to create a custom role.
3. Select Add new role.
4. Under Base role to use as a template, select Guest for this tutorial.
5. Under Role name, enter the custom role’s title.
6. Under Permissions for the custom role, select Read Vulnerability for this tutorial.
7. Select Create a new role.

Interface for creating a custom role

After creating the role you should be able to see the new custom role along with its ID, Base role, and Permissions. Be sure to save the ID as it will be used when we assign the custom role to a guest user.

Security Auditor role created

Now we must assign the custom role to a group or project member. This can be done as follows:

1. Invite a user as a direct member with the Guest role to your top-level group where the custom role was created.
2. You can invite them to a sub-group or private project within the top-level group as well.

• The guest user should not be able to see any code within the project they have been assigned to.
• Open your terminal.

3. Export the required environment variables:

• Your personal access token with API scope

$ export TOKEN=glpat-XXXXXXXXXXXX
$ echo $TOKEN
glpat-XXXXXXXXXXXX

• The ID of the user we will be granting a custom role to. You can obtain the user id by providing the username to the User API. For more information on using the GitLab API, see the REST API documentation.

$ curl "https://gitlab.example.com/api/v4/users?username=fjdiaz"
[{"id":4710074,"username":"fjdiaz","name":"Fern","state":"active","locked":false,"avatar_url":"https://gitlab.com/uploads/-/system/user/avatar/4710074/avatar.png","web_url":"https://gitlab.com/fjdiaz"}]

$ export USER_ID=4710074
$ echo $USER_ID
4710074

• The ID of the custom role. You can obtain the custom role ID from the ID column in the custom roles UI or the member roles API.

$ export CUSTOM_ROLE_ID=1000782
$ echo $CUSTOM_ROLE_ID
1000782

• The ID of your group or project. You can obtain the group id from the group UI or using the groups API. You can obtain the project ID from the project UI or using the projects API.

$ export GROUP_ID=10087220
$ echo $GROUP_ID
10087220

$ export PROJECT_ID=45738177
$ echo $PROJECT_ID
45738177

4. Associate the guest user with the custom role using the appropriate group or project APIs.

• If the user just needs to role in a project, update the project membership:

"Authorization: Bearer $TOKEN" --data '{"member_role_id": $CUSTOM_ROLE_ID, "access_level": 10}' "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/members/$USER_ID"

• If the user just needs to role in a group, update the group membership:

$ curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{"member_role_id": $CUSTOM_ROLE_ID, "access_level": 10}' "https://gitlab.example.com/api/v4/groups/$GROUP_ID/members/$USER_ID"

Now that the custom role has been applied to a guest user, when they login, they can see the Vulnerability dashboard present in the Secure tab. Notice, however, that they are still not allowed to see the source code.

This is useful because it allows users to audit the system without being able to make changes to the code base, which applies the PoLP for those auditing the system for vulnerabilities.

Security policies

GitLab provides security policies to help you achieve least privilege access. There are two different types of security policies provided by GitLab:

• Scan Execution policies allow project maintainers and administrators the confidence of knowing that the scans they set up have not been changed, altered, or disabled.
• Merge Request Approval policies prevent insecure code from being merged into production without appropriate approval.

Some examples of how both policy types can be used in unison to provide least privilege access are as follows:

• remove the ability for developers to disable security scanners
• remove the ability for developers to merge insecure code

Policies are stored in a separate repo from the project they are being applied to called the Security Policy Project (SPP). This allows for separate permissions to be set to the SPP vs. the application repo, thus strengthening your ability to separate duties and apply PoLP.

Security policy hierarchy

To enforce the policies contained in an SPP you link it to a project, subgroup, group, or multiples of each. An SPP can contain multiple policies but they are enforced together. An SPP enforced on a group or subgroup applies to everything below the hierarchy, including all subgroups and their projects.

Security policies can be managed via the policy management UI as well as via yaml. Using the policy editor you can create, edit, and delete policies.

Policy management interface

Feel free to leverage the Simple Notes demo environment to try this yourself by following the provided DevSecOps tutorial.

Creating a Scan Execution policy

Now let's take a look at how to create a Scan Execution policy. Before getting started make sure you have met the following criteria:

• GitLab Ultimate tier in the top-level group
• Owner role to create/assign an SPP
• Developer role or greater to create/edit/delete individual security policies

We will be creating a policy that automatically runs a SAST scan with each pipeline, regardless of the SAST template is defined within the gitlab-ci.yml:

1. On the left sidebar, select Search or go to and search for the project to which you wish to add a policy.
2. On the project left sidebar, go to Secure > Policies.
3. Select New policy.
4. In the Scan Execution Policy section, select Select policy.
5. Complete the fields:
   • Name: The name of the policy
   • Description: The description of the Policy
   • Policy status: Whether it is enabled or not
   • Actions: What actions to take when the defined conditions are met

Scan Execution policy actions

• Conditions: Conditions which must be met (a pipeline is triggered or on a set schedule) in order for an action to take place.

  

Scan Execution policy conditions

• Press the Configure with a merge request button.

Now that the policy has been created, all we need to do is run a pipeline to see that SAST will be present even if it is not defined in the .gitlab-ci.yml.

Creating a Merge Request Approval policy

Now let's take a look at how to create a Merge Request Approval policy. Before getting started make sure you have met the following criteria:

• GitLab Ultimate tier in the top-level group
• Owner role to create/assign an SPP
• Developer role or greater to create/edit/delete individual security policies
• Security scanners added to project

We will be creating a policy that requires approval from project maintainers if any security scanner detects a vulnerability when compared with any branch:

1. On the left sidebar, select Search or go to and search for the project to which you wish to add a policy.
2. On the project left sidebar, go to Secure > Policies
3. Select New policy
4. In the Merge Request Approval policy section, select Select policy.
5. Complete the fields:
   • Name: The name of the policy
   • Description: The description of the policy
   • Policy status: Whether it is enabled or not
   • Rules: The conditions which must be met for an action (require approval) to take place.

Merge Request Approval policy rules

• Actions: The action to be taken whenever the conditions in the rules (defined vulnerabilities/licenses detected) are met.

Merge Request Approval policy actions

• Override project approval settings: If selected, the following choices will overwrite project settings but only affect the branches selected in the policy.

Merge Request Approval policy approval settings

6. Press the Configure with a merge request button.

Now that the policy has been created, all we need to do is run a pipeline and if SAST detects any vulnerabilities then approvals will be required from the selected approver before the code change can be merged. Merge Request Approval policies can be used with all GitLab security scanners, including license scanning.

Merge Request Approval policies blocking code from being merged in an MR

Branch protections and Code Owners

Branch protections allow you to impose additional restrictions on particular branches within your repository. This further strengthens the PoLP for the interactions on a particular set of branches.

For example, a protected branch can control:

• which users can merge into the branch
• which users can push to the branch
• if users can force push to the branch
• if changes to files listed in the CODEOWNERS file can be pushed directly to the branch
• which users can unprotect the branch

Applying branch protections

Branch protections are available in all tiers and offerings of GitLab. Branch protections can be applied to a single project or a group of projects. You can apply branch protections for required roles to push and merge as follows:

1. On the left sidebar, select Search or go to and find your project or group.
2. Select Settings > Repository.
3. Expand Protected branches.
4. Select Add protected branch.
   • For groups, from the Branch text box, type the branch name or a wildcard.
   • For projects, from the Branch dropdown list, select the branch you want to protect.
5. From the Allowed to merge list, select a role that can merge into this branch.
6. From the Allowed to push and merge list, select a role that can push to this branch.
7. Select Protect.

You should now see the protected branch added to the list.

Protected branches settings

The Owner role is required to add branch protections to a group and the Maintainer role or greater is required to add branch protections to a project.

Code Owners

If you want to further limit what files developers can perform changes on, one of the best features to implement is Code Owners. Code Owners allows you to define who has the expertise for specific parts of your project’s codebase. Defining the owners of files and directories in Code Owners will:

• require owners to approve changes as well as merge requests before they merge into a protected branch
• identify owners by displaying the Code Owner names on the files and directories they own

To set up Code Owners, follow these steps:

1. Create a CODEOWNERS file in your preferred location.
2. Define some rules in the file following the Code Owners syntax reference. You can configure all eligible approvers' approval rules and require Code Owner approval on a protected branch.
3. Commit your changes, and push them up to GitLab.

Now, when looking at files, you can see who the Code Owners are for a particular file.

Code Owners displayed for file

If you implement Code Owner approvals, then when creating a merge request, the Code Owners must approve before the code can be merged.

Code Owners approvals

Additional approval settings

There are additional approval settings that can be applied before code can be committed with a merge request. These additional approval settings are as follows:

• prevent approval by author
• prevent approvals by users who add commits
• prevent editing approval rules in merge requests
• require user re-authentication (password or SAML) to approve

Additionally, whenever a commit is added, you can:

• keep approvals
• remove all approvals
• remove approvals by Code Owners if their files changed

Additional Approval settings

To configure additional approval settings you can perform the following steps:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Merge requests.
3. Scroll down to the Merge request approvals section.
4. Under Approval settings select the approval settings you would like to apply.
5. Press the Save changes button.

These can also be applied to your top-level group by performing the following steps:

1. On the left sidebar, select Search or go to and find your top-level group.
2. Select Settings > General.
3. Expand the Merge request approvals section.
4. Under Approval settings select the approval settings you would like to apply.
5. Press the Save changes button.

By leveraging these approval settings you can make sure that code always obtains oversight by a person who was not involved in creating the code, thereby preventing a conflict of interest.

Compliance pipelines and frameworks

You can create a compliance framework that is a label to identify that your project has certain compliance requirements or needs additional oversight. The label can optionally enforce compliance pipeline configuration to the projects on which it is applied.

Feel free to leverage the Compliance Frameworks Demo group to see an example of compliance frameworks and their usage.

Create a compliance pipeline

To create a compliance pipeline, all you need to do is create a new project which will store a .gitlab-ci.yml file that we wish to use in another project. The new compliance pipeline project can have separate permissions from the project to which you will apply it. This is beneficial because it prevents developers from making changes to pipelines that must run.

You can see I have created the following pipeline definition which:

• runs the SAST security scanner
• runs the secret detection scanner
• runs a SOC2 compliance job
• runs the original pipeline defined in the project to which we will apply this pipeline. This allows developers to focus on the actual application development and the compliance team to focus on defining the SOC2 rules.

Create and apply a compliance framework

Now that the compliance pipeline for SOC2 has been defined, we must define a compliance framework and apply it to our project. In this case, I will apply it to my Accounting Department project.

To create a compliance framework label, follow these steps:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand the Compliance frameworks section.
4. Click the Add framework button.
5. Create a new compliance framework and populate the following sections:
   • Name: The name of your compliance framework
   • Description: A description of your compliance framework
   • Compliance pipeline configuration: The location of the compliance pipeline to run.
   • Background color: A color for the compliance framework label

Creating a compliance framework

6. Press the Add framework button.

And now you should see your newly added framework under active compliance frameworks.

Active compliance frameworks

Now let’s go ahead and assign this compliance label to our Accounting Department project:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > General.
3. Expand Compliance frameworks.
4. Select the compliance framework created above.

Adding a compliance framework

5. Select Save changes.

The project should now have the compliance framework label applied.

Project running a compliance pipeline

This enables separation of duties and prevents compliance pipelines from being altered by those without permissions.

Security Policy Scope and Pipeline Execution Over the past several releases, GitLab has introduced two experimental features, Security Policy Scope and Pipeline Execution, to make it even easier to adhere to PoLP. These features are very similar to Compliance Pipelines and Compliance Frameworks and can be managed from GitLab’s security policy UI.

Note: These features are currently considered experimental. An experiment is a feature that is in the process of being developed. It is not production ready. We encourage users to try experimental features and provide feedback.

The pipeline execution policy action introduces a new scan action type into Scan Execution policies for creating and enforcing custom CI in your target development projects. You can execute a custom pipeline along with your current pipeline. This allows you to enforce compliance by always forcing particular actions to run that are not just security scanners and that cannot be overwritten by those without permissions.

Pipeline Execution policy scope selection - insert code block

Pipeline Execution policy scope selection - link existing CI file

The Security policy scope can be applied to either Merge Request Approval or Scan Execution policies. Scopes enable you to administer policies with a particular scope, meaning you can:

• Include only projects containing a compliance framework label
• Include or exclude selected projects from enforcement

To enable these experimental features, follow these steps:

1. On the left sidebar, select Search or go to and find your top-level group.
2. Select Settings > General.
3. Expand Permissions and group features.
4. Scroll down to the Security policy management section.
5. Select the following checkboxes Security policy pipeline execution action: Create and enforce custom CI jobs and scripts using this new policy action.
6. Security policy scopes: Granularly scope each policy you create to projects containing a compliance framework label, or a list of projects.
7. Enforce for all subgroups (optional): Subgroups cannot change these settings.
8. Scroll down to the Experiment and Beta features section.
9. Select the Use Experiment and Beta features checkbox.
10. Scroll down and press the Save changes button.

Now, whenever you are creating a security policy, the following options will be available:

• Inserting a CI code block (Scan Execution policy only)
• Loading CI/CD code from file (Scan Execution policy only)
• Linking an existing CI file from another project (Scan Execution policy only)
• Scoping a policy to projects with selected compliance framework (Group Level only)
• Scoping a policy towards specific projects (Group Level only)
• Scoping a policy towards all projects in group (Group Level only)

To learn more about these features, check out the following documentation:

• Pipeline Execution Policy action (Scan Execution policy)
• Security Policy Scopes (Scan Execution policy)
• Security Policy Scopes (Merge Request Approval policy)

Additional resources

Thanks for reading! These are some of the ways that GitLab allows you to strengthen your organization's security posture through the enablement of PoLP. To learn more about GitLab and the other ways we can strengthen your organization's security throughout all parts of the SDLC, check out the following links:

• GitLab Security and Compliance
• GitLab Application Security Documentation
• GitLab DevSecOps Demo Project
• GitLab DevSecOps Tutorial
• GitLab Roles and Permissions Documentation
• GitLab Custom Roles Documentation
• GitLab Security Policies Documentation
• GitLab Compliance Frameworks Documentation
• GitLab Code Owners Documentation
• GitLab Branch Protections Documentation