Aguardic logoAguardic/Docs

Search documentation

Search all documentation pages

Get Started

GitLab Integration

Enforce policies on GitLab merge requests and pipelines.

Overview

The GitLab integration connects Aguardic to your GitLab projects via OAuth. When merge requests are opened or updated, Aguardic evaluates the changes against your policies and reports results as commit statuses on the merge request.

Setup

1

Connect via OAuth

Go to Integrations > Add Integration > GitLab in the Aguardic dashboard and click Connect. You'll be redirected to GitLab to authorize Aguardic to access your projects.
2

Bind policies

After connecting, go to Policy Bindings and map your policies to the GitLab integration. You can bind policies to:

All projectsEvery project connected through the integration
Specific projectsIndividual projects selected by name
Specific branchesTarget branches like main or production
3

Configure enforcement

Choose how Aguardic enforces policy results on GitLab:

BLOCKSets the commit status to failed, preventing merge when pipeline status checks are required
APPROVAL_REQUIREDSets the commit status to pending, requiring manual intervention before merge
WARNSets the commit status to success but includes violation details in the status description
MONITOR_ONLYNo visible action on GitLab, violations logged in Aguardic only

How It Works

1

MR opened or updated

A developer opens or updates a merge request
2

Webhook received

GitLab sends a webhook to Aguardic
3

Fetch MR data

Aguardic fetches the MR diff and metadata
4

Policy evaluation

The governance engine evaluates against bound policies
5

Report results

Results are posted as a commit status on the merge request, with violation details in the description

What Gets Evaluated

MR title and descriptionCheck naming conventions, required sections, template compliance
File changesScan diffs for sensitive data, banned patterns, or restricted file types
Commit messagesEnforce commit message format (e.g., Conventional Commits)
Branch namesValidate branch naming conventions (e.g., feature/, fix/)

Pipeline Integration

For full enforcement, configure your GitLab project to require pipeline success before merging:

  1. Go to Settings > Merge requests in your GitLab project
  2. Under "Merge checks", enable "Pipelines must succeed"
  3. Aguardic's commit status will be included in the pipeline check

With pipeline checks enabled and enforcement set to BLOCK, developers cannot merge MRs that violate your policies.

Example Policies

Enforce MR Description Format

Require merge requests to include a structured description:

  • Field: description
  • Operator: MATCHES
  • Value: ## (Summary|Changes|What) (must include a markdown heading)
  • Severity: MEDIUM

Block Secrets in Commits

Prevent credentials from being committed:

  • Field: content
  • Operator: MATCHES
  • Value: (AKIA[A-Z0-9]{16}|-----BEGIN (RSA |EC )?PRIVATE KEY-----|sk-[a-zA-Z0-9]{48})
  • Severity: CRITICAL

Enforce Branch Naming

Require branches to follow a naming convention:

  • Field: branch
  • Operator: MATCHES
  • Value: ^(feature|fix|hotfix|release)/[a-z0-9-]+$
  • Severity: LOW

Next Steps

GitHubBitbucket