GitHub Integration

Overview

The GitHub integration connects Aguardic to your GitHub repositories via a GitHub App. When pull requests are opened or updated, Aguardic evaluates the changes against your policies and reports results as check runs.

Setup

1. Install the GitHub App

Go to Integrations > GitHub in the Aguardic dashboard and click Connect. You'll be redirected to GitHub to install the Aguardic GitHub App.

Select the repositories you want to govern and authorize the installation.

2. Bind Policies

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

• All repositories in the integration
• Specific repositories by name
• Specific branches (e.g., only main or production)

3. Configure Enforcement

Choose how Aguardic enforces policy results on GitHub:

• BLOCK — Fails the check run (conclusion: failure), preventing merge with branch protection
• APPROVAL_REQUIRED — Sets check to "action required" (conclusion: action_required), requiring manual approval before merge
• WARN — Passes the check run (conclusion: neutral) but includes violation details in the check summary
• MONITOR_ONLY — No visible action on GitHub, violations logged in Aguardic only

How It Works

1. A developer opens or updates a pull request
2. GitHub sends a webhook to Aguardic
3. Aguardic fetches the PR diff and metadata
4. The governance engine evaluates against bound policies
5. Results are posted as a check run named "Aguardic Policy Check" on the PR, with a markdown summary of any violation details

What Gets Evaluated

• PR title and description — Check naming conventions, required sections
• File changes — Scan diffs for sensitive data, banned patterns, or required approvals
• Commit messages — Enforce commit message format
• Branch names — Validate branch naming conventions

Branch Protection

For full enforcement, enable branch protection rules on GitHub:

1. Go to Repository Settings > Branches > Branch protection rules
2. Enable "Require status checks to pass before merging"
3. Select the Aguardic check from the list

Example Policies

Require PR Description

Ensure all PRs have a meaningful description:

• Field: description
• Operator: MATCHES
• Value: .{20,} (at least 20 characters)
• Severity: MEDIUM

Block Secret Commits

Prevent credentials from being committed:

• Field: content
• Operator: MATCHES
• Value: (AKIA[A-Z0-9]{16}|sk-[a-zA-Z0-9]{48}|ghp_[a-zA-Z0-9]{36})
• Severity: CRITICAL

Next Steps

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