GitLab Integration

Overview

The GitLab integration connects your GitLab instance to Fencer through an OAuth application you create in GitLab. It enables automatic code scanning of the projects you add on push and merge request events, commit status reporting, and identity sync for group members. You can connect GitLab.com or any self-managed GitLab instance. In the catalog it is listed as GitLab (Code).

Prerequisites

• An active Fencer organization with a valid subscription.
• The Administrator role in your Fencer organization.
• Maintainer or Owner access to the GitLab group, so you can create a group application with the api scope. Projects owned by individual users are not supported.
• The Fencer application URL must be reachable from your GitLab instance (required for webhooks).

How it works

Fencer uses GitLab’s OAuth 2.0 authorization flow. You create a GitLab OAuth application, provide its credentials to Fencer, and authorize the connection. Once authorized, Fencer uses the GitLab API to list projects, register per-project webhooks, and trigger code scans.

When you add a repository, Fencer registers a webhook on that GitLab project that listens for push events, tag push events, merge request events, comment (note) events, and repository update events. Push and tag events trigger scans on the pushed branch or tag. Merge request events trigger scans on the source branch. Scan results are reported back to GitLab as commit statuses, so you can see scan outcomes directly on your commits and merge requests.

Usage / Configuration

Creating a GitLab OAuth Application

1. In GitLab, open your group’s Settings and select Applications in the sidebar (or go to the /-/settings/applications path of your group).
2. Enter the following:
   • Name: Fencer
   • Redirect URI: the callback URL shown in the Fencer connect wizard, which is /integrations/gitlab/callback/ on your Fencer domain.
   • Scopes: api
3. Ensure Confidential is checked, then click Save Application.
4. Copy the Application ID and Secret from the page that follows.

Connecting GitLab to Fencer

1. Navigate to Admin > Integrations in your Fencer organization.
2. Click the GitLab (Code) card, then click Continue.
3. Fill in the connection form:
   • Gitlab url: The base URL of your GitLab instance (e.g., https://gitlab.com).
   • Gitlab group path (optional): The path of your GitLab group (e.g., my-group/my-subgroup). Leave blank to connect to the entire instance.
   • Gitlab application id: The OAuth Application ID from GitLab.
   • Gitlab application secret: The OAuth Application Secret from GitLab.
4. Click Connect GitLab. A popup redirects you to GitLab to authorize the application.
5. After authorization, the popup closes and Fencer opens the connection’s edit page, where you add repositories.

Note

If you specify a group path, Fencer scopes project discovery and identity sync to that group and its subgroups. Without a group path, all projects accessible to the authorized user are available.

Adding Repositories

1. Go to Admin > Integrations and click Edit on your GitLab connection.
2. Click Add repositories and search for a GitLab project.
3. Click Add next to the project. Fencer creates the repository asset, registers a webhook on the GitLab project, and triggers an initial code scan.

Removing Repositories

1. From the GitLab connection edit page, find the repository under Connected repositories.
2. Click Remove repository, then confirm with Remove.
3. Fencer removes the webhook from the GitLab project and stops scanning the repository.

Code Scanning on Push and Merge Requests

Code scans are triggered automatically when GitLab sends webhook events:

• Push events: Triggered when code is pushed to a branch within the repository’s Branch scope. Fencer scans the pushed commit. Pushes to the default branch are scanned only while Scan on push is on in the repository’s settings.
• Tag push events: Triggered when you push a new tag. Fencer scans the tagged commit.
• Merge request events: Triggered when a merge request is opened, reopened, or updated. Fencer scans the source branch at the latest commit.

Commit Status Reporting

Fencer reports scan progress back to GitLab as commit statuses. The status progresses through:

1. pending — Scan is queued.
2. running — Scan is in progress.
3. success or failed — Scan completed. failed means the scan broke one of the repository’s Checks settings (for example, new vulnerabilities at or above the configured severity); otherwise the status is success.

If you cancel a scan, Fencer sets the status to canceled. If a scan crashes or times out, Fencer sets the status to failed. A push to a branch outside the repository’s Branch scope gets a skipped status.

Automated Fix Merge Requests

When Fencer generates automated fixes for vulnerabilities (e.g., dependency updates), it creates merge requests directly on the GitLab project. The fix is committed to a new branch and a merge request is opened against the branch where the vulnerability was last found.

Identity Sync

When you configure a group path, Fencer syncs your GitLab group members as identities when you connect and then daily, when your plan includes identity management. This includes:

• Usernames, display names, and public email addresses
• Access level mapping (owner, maintainer, member)
• User state tracking (active, blocked, deactivated)

Updating Connection Settings

1. Go to Admin > Integrations and click Edit on your GitLab connection.
2. Update the Gitlab url, Gitlab group path, or Gitlab application secret as needed, and click Save changes. Leave the secret blank to keep the stored one.
3. The Gitlab application id cannot be changed after initial setup.
4. If your OAuth tokens are invalid or have expired, the edit page shows a warning instead of the repository list. Click Reconnect GitLab to authorize again.

Disconnecting

1. Go to Admin > Integrations and find your GitLab connection under Active Integrations.
2. Click Remove on the connection, then confirm.
3. Fencer removes all project webhooks, clears stored OAuth tokens, and removes all associated repositories from scanning.

GitLab Monitor (SIEM)

The separate GitLab (Monitor) integration forwards GitLab audit events to Security Monitoring, where detection rules evaluate them. Fencer polls GitLab’s Audit Events REST API every five minutes with a personal access token. It needs a Fencer plan that includes Security Monitoring, and GitLab Premium or Ultimate (GitLab only exposes audit events on those tiers).

1. In GitLab, create a personal access token. On GitLab 19.2 and later, prefer a fine-grained token scoped to the group, with Audit Event: Read, Group: Read, and Project: Read. Otherwise create a classic token with the api (or read_api) scope. The token’s owner needs the Owner role on the group (Maintainer or above for a project, admin for a self-managed instance); otherwise GitLab returns only that user’s own events.
2. In Fencer, go to Admin > Integrations, click the GitLab (Monitor) card, and click Continue.
3. Fill in Integration Name, GitLab base URL (https://gitlab.com by default; it must use HTTPS), Personal access token, What to monitor (Instance (self-managed admin), Group and everything under it, or A single project), and Group or project (a path such as my-company, or a numeric ID).
4. Click Connect.

One connection covers a whole group: Fencer discovers every subgroup and project beneath it, including ones created later, and polls each one’s audit feed. GitLab.com has no instance-level audit events, so choose a group or project there. Without Group: Read and Project: Read, Fencer can poll the group you name but not what sits beneath it. After connecting, the edit page lets you rename the connection.

Examples

Typical workflow with a merge request

1. A developer opens a merge request on a GitLab project you added to Fencer.
2. GitLab sends a merge request webhook event to Fencer.
3. Fencer sets a pending commit status on the merge request’s latest commit.
4. The code scan runs, analyzing the source branch for vulnerabilities and secrets.
5. On completion, the commit status updates to success or failed.
6. The developer reviews the scan status directly in the GitLab merge request interface.

Connecting a self-hosted GitLab instance

1. On your self-hosted GitLab, create an OAuth application under Admin Area > Applications or at the group level.
2. Set the redirect URI to the Fencer callback URL shown in the connect wizard.
3. In Fencer, enter your self-hosted GitLab URL (e.g., https://gitlab.example.com) and the OAuth credentials.
4. Authorize the connection. Fencer communicates with your instance’s API at /api/v4.

Caution

Your self-hosted GitLab instance must be able to reach Fencer’s webhook endpoint. If your instance is behind a firewall, ensure the Fencer URL is allowlisted for outbound connections.

Troubleshooting

• Webhook registration fails: Ensure the Fencer application URL is reachable from your GitLab instance. GitLab validates the webhook URL on creation.
• Commit statuses not appearing on merge requests: Verify the OAuth token is still valid by opening the connection’s edit page. If it shows the expired-token warning, click Reconnect GitLab.
• Project search returns no results: If you configured a group path, Fencer only returns projects within that group and its subgroups. Verify the group path is correct and the authorized user has access to the group.
• Identity sync not running: You must configure a group path for identity sync. Without one, Fencer cannot determine which users to sync.
• OAuth authorization fails: Verify the Application ID, Application Secret, and redirect URI match exactly between your GitLab OAuth application settings and Fencer, and that the application has the api scope.

Related pages

• Integrations Overview
• Code Scanning
• Automated Remediation
• Identity Management
• Security Monitoring (SIEM)