GitLab Integration

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 projects in the integration
• Specific projects by name
• Specific branches (e.g., only main or production)

3. Configure Enforcement

Choose how Aguardic enforces policy results on GitLab:

• BLOCK — Sets the commit status to failed, preventing merge when pipeline status checks are required
• APPROVAL_REQUIRED — Sets the commit status to pending, requiring manual intervention before merge
• WARN — Sets the commit status to success but includes violation details in the status description
• MONITOR_ONLY — No visible action on GitLab, violations logged in Aguardic only

How It Works

1. A developer opens or updates a merge request
2. GitLab sends a webhook to Aguardic
3. Aguardic fetches the MR diff and metadata
4. The governance engine evaluates against bound policies
5. Results are posted as a commit status on the merge request, with violation details in the description

What Gets Evaluated

• MR title and description — Check naming conventions, required sections, template compliance
• File changes — Scan diffs for sensitive data, banned patterns, or restricted file types
• Commit messages — Enforce commit message format (e.g., Conventional Commits)
• Branch names — Validate 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

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

• GitHub Integration — Similar setup for GitHub
• Bitbucket Integration — Similar setup for Bitbucket
• Your First Policy — Deep dive into policy creation