Our GitLab integration automates compliance checks and evidence collection for these five security controls:
New changes in production branches require at least one independent approval prior to merge.
Individual pull requests have at least one independent approval prior to merging into production branches.
SAST testing is done on all production pull requests.
Individual pull requests undergo integration testing prior to merging into production branches.
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
In the Secureframe application on the Monitoring dashboard, click Asset Inventory in the left navbar.
Click the Repositories tab.
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). 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.
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.You can set default configurations for new repositories that are added.
How to configure Merge Request
In Gitlab, navigate to your repository.
Click Settings in the left navbar. Choose General, and expand the Merge request approvals section.
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
In Gitlab, navigate to your repository.
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.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 |
| 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. |
| Grants read access to the API, including all groups and projects, the container registry, and the package registry. |
| Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. |
| Grants read-only access to container registry images on private projects. |
| Grants permission to authenticate with GitLab using OpenID Connect. Also gives read-only access to the user’s profile and group memberships. |
| Grants read-only access to the user’s profile data using OpenID Connect. |
| 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 |
| Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. |
| Grants read access to the API, including all groups and projects, the container registry, and the package registry. |
| 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 | Groups |
id path name require_two_factor_authentication | |
Group Members (Users) | Group Members (Users) |
id name username access_level email The email attribute is only visible for users with public emails. | |
Group Projects (Repositories) | Group Projects (Repositories) |
id visibility web_url name | |
Project Branches | Project Branches |
name | |
Project Merge Requests | Project Merge Requests |
id title state labels author author.username created_at merged_at | |
Merge Request | Merge Request |
Pipelines id | |
Pipeline Jobs | Pipeline Jobs |
name | |
Merge Request Approvals | Merge Request Approvals |
approved_by approved_by.user approved_by.user.username | |
MR Approval Rules | MR Approval Rules |
protected_branches protected_branches.name approvals_required |
Frequently Asked Questions (FAQ)
Why am I getting an "Error connecting to Organization"
I set a test start date. Why do old code integration failures still appear?
The test start date (under Integrations → GitLab → Settings) controls which merged merge requests Secureframe evaluates. It is tied to the merge date, not when you connected the integration or when you changed the date.
Merge requests merged before the start date should not be evaluated going forward, but you may still see historical failures until tests re-evaluate after a successful sync. Run a manual sync on the integration and allow time for tests to refresh.
Confirm per-repo settings under Asset Inventory → Repositories → [repo] → Configuration. Empty production branch, testing check, or SAST fields can cause failures even when the start date is correct.
If old failures persist for merges after your start date, contact Support with the repo name, start date, and one example failing merge request.
An out-of-scope repository still appears in my code integration test or export. What should I check?
Confirm the project is excluded from the connected GitLab group or project scope, then re-sync the integration.
In Secureframe, verify the repository is marked out of scope or archived in Asset Inventory → Repositories if applicable.
If a project was recently removed from scope, run a manual sync and allow tests to refresh before checking exports.
What is the difference between repo scoping, test start date, and per-repo configuration?
Repo scoping (GitLab group/project access) determines which repositories Secureframe can pull data from.
Test start date determines which merged merge requests are evaluated for code integration tests.
Per-repo configuration (Asset Inventory → Repositories → Configuration) defines production branches, emergency labels, and which CI/SAST checks apply to each repo.
All three must be aligned for code integration tests to pass. Fixing one alone may not resolve failures.
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.