GitLab Self Managed (On-Prem)

Integrate Cortex Cloud Application Security with your GitLab Self Managed (On-Prem) version control system (VCS) to enable security scans for exposed secrets, infrastructure-as-code (IaC) misconfigurations, vulnerabilities, package operational risks, and license compliance issues in your repositories. This integration allows you to analyze, prioritize, and resolve detected issues efficiently.

Architecture and connectivity

Whether you need a Transporter depends on your GitHub Enterprise on-prem accessibility. If your instance is hosted on a private domain, a direct connection fails because Cortex Cloud cannot reach the on-premises host.

To solve this, the Transporter over Broker VM bridges the connection by:

• Living inside your network as an applet on the Broker VM
• Initiating an outbound WebSocket connection to the cloud, meaning no inbound firewall rules or direct IP access are needed
• Proxying requests from the cloud to internal resources, allowing Cortex Cloud to perform secure code scanning without exposing your internal network to the public cloud

Connection guidelines

• Private domains (isolated environments): Always use a Transporter. Make sure the Transporter has an AppSec applet enabled so it appears in the onboarding wizard. An egress rule is not required
• Public domains (internet-accessible): If your GitHub Enterprise on-prem instance is already internet-accessible or managed via existing connectivity solutions (such as a VPN or network peering), a Transporter is not needed. An egress rule is required

For more information on Transporter, refer to Transporter over Broker VM.

If your GitLab self-managed instance is already internet-accessible or managed via existing connectivity solutions (such as a VPN or network peering), the Transporter is not needed.

How to integrate GitLab Self Managed (On-Prem)

Prerequisite

• Cortex Cloud user permissions: Ensure you have View/Edit permissions for Data Sources and Integrations (RBAC: AppSec Admin or Instance Administrator)
• Gitlab permissions: Authorize the user integrating Cortex Cloud Application Security with your GitLab Self Managed (On-Prem) instances with the following permissions:

  • Maintainer permissions. Grants sufficient permissions to configure external integrations, manage repository access, and adjust CI/CD settings
  • api: Grants full read and write access to the API, including all groups and projects, as well as permissions to interact with the container registry, the dependency proxy, and the package registry
  • Administrator repository permissions: In order to scan pull requests (PRs), the user performing the integration must have administrative privileges for the repositories. This enables Cortex Cloud Application Security to set up subscription webhooks for the selected repositories
• Onboarding port: Port 443 is required for all on-premise onboarding for outbound HTTPS communication to Cortex Cloud. If the Transporter is used, it specifically uses port 443 for its WSS tunnel
• Egress path: Create an egress path to establish the designated route for outbound data transmission from Cortex Cloud to third party services. For more information about configuring egress paths,refer to Egress configurations

Onboarding steps

1. In the Cortex Cloud tenant.

   1. Navigate to Settings → Data Sources & Integrations → + Add New.
   2. Search for GitLab Self Managed (On-Prem) , hover over it, and click Add or Add Another Instance if an instance has already been onboarded.
   3. Enter your domain in the Configure Domain step of the wizard and click Register.

      Note

      The domain is the hostname associated with your GitLab Self Managed (On-Prem) instance.

      You are redirected to your GitLab Self Managed (On-Prem) instance register Cortex AppSec as an application. Additionally, the Register OAUTH App step of the integration wizard is displayed.
   4. Optional: Connect a Transporter: Select your Broker VM and associated Transporter applet from the provided menus.

      Note

      For more information about the Transporter, including setup instructions, refer to Transporter over Broker VM.
   5. Copy the Application Name, Homepage URL and Authorization Callback URL values from their respective fields.
2. On the GitLab Self Managed (On-Prem) console:

   1. Access GitLab Self Managed (On-Prem) → User Settings → Applications.
   2. Paste the values copied in step 1d above in their respective fields.
   3. Select api as the application scope and then Save.
   4. Once created, copy and save the generated Application ID and Secret values for the new Cortex AppSec application.
3. On the Cortex Cloud console.

   1. Select Next on the Register OAUTH App step of the wizard.

      The Set Client ID and Secret step of the wizard is displayed.
   2. Paste the GitLab Self Managed (On-Prem) Application ID and Secret values copied in step 2d above and click Next.
   3. Under Selection Options of the Select Repositories step of the wizard, choose the repositories to be connected to the instance:

      • Permit all existing repositories
      • Permit all existing and future repositories
      • Select Choose from repository list and select repositories from the list
   4. Click Save.
   5. Click Close on the final step of the wizard.

      Note

      Ensure that you receive the Instance Successfully Created message on this step, indicating successful instance creation.
4. View repository assets and mitigate detected issues.

Verify integration

1. On Data Sources & Integrations, search for GitLab Self Managed (On-Prem).
2. Select the matching result.
3. Locate your instance and confirm its status is Connected.

To manage GitLab Self Managed (On-Prem) integrations, refer to Manage data source integrations.

Subscribed events

Below is a comprehensive list of events to which Cortex Cloud Application Security is subscribed. These events encompass various actions and changes occurring within your GitLab Self Managed (On-Prem) environment that trigger notifications and integrations with Cortex Cloud Application Security.

Read more...

Category	Event	Description
Projects	—	—
—	merge_requests_events	This event is triggered when merge or pull requests are created, updated, merged, closed, or have changes made to them
—	push_events	This event occurs whenever code changes are pushed to a repository, indicating new commits being added to the version control history
—	tag_push_events	This event is triggered when new tags are pushed to a repository
—	note_events	This event is generated when comments or notes are added to various objects within GitLab, such as issues, merge requests, or commits
—	confidential_note_events	Similar to note_events, but specifically for confidential comments or notes that are restricted to certain users or groups
—	issues_events	This event is triggered when issues are created, updated, closed, or have changes made to them
—	confidential_issues_events	Similar to issues_events, but specifically for confidential issues that are restricted to certain users or groups
—	job_events	This event occurs when jobs defined in CI/CD pipelines are created, updated, started, finished, or have changes made to them
—	pipeline_events	This event is generated when pipelines are created, updated, started, finished, or have changes made to them
—	wiki_page_events	This event occurs when changes are made to wiki pages within GitLab, including creation, updates, and deletions
—	deployment_events	This event is triggered when deployments are created, updated, started, finished, or have changes made to them
—	releases_events	This event occurs when releases are created, updated, published, or have changes made to them
Groups	—	—
—	subgroup_events	This event is specific to GitLab groups and occurs when changes are made to subgroups within a group hierarchy
System	repository_update_events	This event occurs whenever there are updates or changes made to a GitLab repository, including actions such as new commits, branch operations, tag updates, and modifications to repository settings

Manage the integration

Instance-level actions

1. Navigate to Settings → Data Sources & Integrations and search for GitLab Self Managed (On-Prem).
2. Select the matching result.
3. Locate your instance from the displayed list, right-click it, then select an option:

   • Edit instance: Opens the onboarding wizard, where you can change the instance configuration.
   • Delete instance: Deletes the instance and previous scan data.
   • Copy entire row: Copies all row values to the clipboard.

Repository-level actions

Right-click a connected repository to Set Scanned Branches, run a manual scan through Scan Repository, modify the Scan Configuration, or Remove Repository entirely. You can toggle specific scanners and manage PR behavior in Scan Configuration.

1. Locate your instance. See Verify integration above.
2. Select the instance. A list of connected repositories appears.
3. Right-click a repository, select the required action, then click Save.