Version Control

Search

GitLab

Our GitLab integration automates compliance checks and evidence collection for these five security controls:

  1. New changes in production branches require at least one independent approval prior to merge.
  2. Individual pull requests have at least one independent approval prior to merging into production branches.
  3. SAST testing is done on all production pull requests.
  4. Individual pull requests undergo integration testing prior to merging into production branches.
  5. Individual pull requests undergo dependency checks prior to merging into production branches.

To take advantage of our GitLab integration, you must be using a pull request development model rather than a direct commit to master model.

How to enable the new GitLab

  1. In the Secureframe application on the Monitoring dashboard, click Asset Inventory in the left navbar.
  2. Click the Repositories tab.
  3. For EACH in-scope repository, click the repository row and follow the instructions provided to configure your test settings. Provide these values where applicable:
    • Production branch names(s). In order to add a production branch, the branch must have at least one merged pull request.
    • Emergency label. Secureframe will not apply checks to pull requests with this label.
    • Integration testing solution(s).
    • SAST solution(s).
    • Dependency checking solution(s).

If any fields are left empty, the associated test will fail with a message about configurations.
Screenshot 2024-10-04 at 3.19.28 PM.png

  1. You can also set the starting date from which we will run version control testing by navigating to Integrations > Gitlab > Settings. This date defaults to the date that you connected Gitlab in Secureframe. It can be useful to move this date ahead if you do not have the proper compliance configurations in place at the time you are connecting Gitlab.
    More information can be found here about how to configure the date. This date is tied to the pull request merge date.
  2. You can set default configurations for new repositories that are added. 

Screenshot 2024-10-04 at 3.18.00 PM.png

How to configure Merge Request

  1. In Gitlab, navigate to your repository.
  2. Click Settings in the left navbar. Choose General, and expand the Merge request approvals section. 
  3. Specify at least one rule where at least two approvals are required for your master branch (or all branches). For testing purposes, if you have more than one approval rule targeting your production branch then Secureframe evaluates the rule with the highest approval count.

How to verify if individual pull requests are approved

Based on your configurations, you’ll be able to see approval checks underneath applicable PRs. 

How do I create SAST, dependency checks, and integration testing jobs

  1. In Gitlab, navigate to your repository.
  2. Click CI/CD in the left navbar. Choose Editor and configure your pipeline.
    These jobs should be running on pull/merge requests before they merge into the production branch. 
  3. In Secureframe, these jobs can be selected under Testing Checks in Advanced Repository Settings.

API permissions

Our integration uses OAuth to authenticate our app for REST API access to Gitlab resources. The GitLab OAuth 2 applications support scopes which provide the access permissions that Secureframe needs to perform automations.

The set of scopes we request from this integration are:

Scope Permission Details
read_user Grants read-only access to the authenticated user’s profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
read_api Grants read access to the API, including all groups and projects, the container registry, and the package registry.
read_repository Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API.
read_registry Grants read-only access to container registry images on private projects.
openid Grants permission to authenticate with GitLab using OpenID Connect. Also gives read-only access to the user’s profile and group memberships.
profile Grants read-only access to the user’s profile data using OpenID Connect.
email Grants read-only access to the user’s primary email address using OpenID Connect.

You can see details for the available scopes from Gitlab here.

What API permissions does this integration request (self-managed/self-hosted)?

Our integration, when connecting to a self-managed GitLab Instance, uses a Group access token for authentication. The GitLab Access Tokens support limited scopes, which allow various read-only actions that the token holder can perform. These scopes provide Secureframe permissions to access the resources.

Note that there are limitations with the Gitlab integration if a free tier is being utilized. Please reach out to your dedicated Customer Success Manager with questions regarding Gitlab plans.

The set of scopes/permissions we request from this integration are:

Scope Permission Details
api Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry.
read_api Grants read access to the API, including all groups and projects, the container registry, and the package registry.
read_repository Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API.

You can see details on Group access tokens from Gitlab here.

What API fields does this integration pull?

Resources Reference URL & Fields

Groups

id

path

name require_two_factor_authentication

 https://docs.gitlab.com/ee/api/groups.html#list-groups

Group Members (Users)

id

name

username

access_level

email The email attribute is only visible for users with public emails.

 https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project

Group Projects (Repositories)

id

visibility

web_url

name

 https://docs.gitlab.com/ee/api/groups.html#list-a-groups-projects

Project Branches

name

 https://docs.gitlab.com/ee/api/branches.html#list-repository-branches

Project Merge Requests

id

title

state

labels

author

author.username

created_at

merged_at

 https://docs.gitlab.com/ee/api/merge_requests.html#list-project-merge-requests

Merge Request

Pipelines id

 https://docs.gitlab.com/ee/api/merge_requests.html#list-mr-pipelines

Pipeline Jobs

name

 https://docs.gitlab.com/ee/api/jobs.html#list-pipeline-jobs

Merge Request Approvals

approved_by

approved_by.user approved_by.user.username

 https://docs.gitlab.com/ee/api/merge_request_approvals.html#merge-request-level-mr-approvals

MR Approval Rules

protected_branches

protected_branches.name

approvals_required

 https://docs.gitlab.com/ee/api/merge_request_approvals.html#get-project-level-rules

Frequently Asked Questions (FAQ)

Why am I getting an "Error connecting to Organization" when trying to connect to the Gitlab integration?

  • This error may occur if the user account being used does not have sufficient permissions. To successfully connect an integration, the account must have at least Maintainer permissions for the group. If the connection fails, check that the user has the necessary role and update permissions if needed. Additionally, verify that the integration settings and authentication details are correctly configured.

Was this article helpful?

Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.