GitHub Integration

Overview

Aira's GitHub integration scans pull requests against your organization's policies, detecting credentials, PII, and custom violations in code changes. When the scan is clean, Aira can optionally auto-merge the PR.

Setup

Step 1: Install the GitHub App

Go to Dashboard → Integrations → GitHub and click Install on GitHub. Authorize the Aira Governance app on your GitHub organization and select the repositories to monitor.

Step 2: Link the Installation

After installation, return to the dashboard. The GitHub org will appear under "Available to link." Click Link to this org.

Step 3: Enable the Feature Flag

Toggle github_code_governance on in Dashboard → Configuration → Feature Flags.

Step 4: Start Reviewing (Zero Configuration)

Aira immediately starts reviewing PRs with its built-in code review agent — no policies needed. The built-in agent covers:

• Security (critical): Hardcoded secrets, SQL injection, XSS, SSRF, missing auth, weak crypto, insecure deserialization
• Data protection (critical): PII in logs, sensitive data in error messages, missing input sanitization
• Error handling (warning): Empty catch blocks, overly broad catches, missing null checks, non-descriptive errors
• Performance (warning): N+1 queries, unbounded queries, resource leaks, sync blocking in async
• Code quality (warning): console.log/print in production, dead code, magic numbers

Critical findings block the merge. Warning findings are posted as comments but don't block.

Step 5: Add Custom Policies (Optional)

Go to Dashboard → Policies and create policies that match action_type: pr_code_scan. For example:

• Content scan policy: Detect hardcoded credentials, API keys, PII in added code
• AI policy: Use Claude or GPT to review code changes against your standards
• Rules policy: Allow or block based on file paths, PR size, or other conditions

How It Works

When a PR is opened or updated:

1. Aira receives a webhook from GitHub
2. Fetches the changed files and diffs
3. Runs your policies against the changes
4. Posts a review on the PR:
   • No violations: Posts a comment confirming the scan passed
   • Violations found: Posts REQUEST_CHANGES with inline comments on each violation
5. Creates a Check Run showing the scan result

Auto-Merge

When enabled, Aira can automatically merge PRs that pass the governance scan with no violations.

Enabling Auto-Merge

1. Enable github_auto_merge in Feature Flags
2. Ensure github_code_governance is also enabled

How Auto-Merge Works

Clean PRs (0 violations): Aira auto-approves and merges immediately.

PRs with violations: If you've set up an auto-merge policy, Aira passes the violations to the policy AI. The AI decides whether the violations are safe to skip (e.g. typos, minor style issues) or must block the merge (e.g. hardcoded secrets, SQL injection).

The flow:

1. Governance scan runs all policies against the full PR diff (not just the latest commit — prevents bypassing violations with clean follow-up pushes)
2. If github_auto_merge flag is on:
   • 0 violations → approve and merge
   • N violations + auto-merge policy exists → AI evaluates violations against your rules → merge or block
   • N violations + no auto-merge policy → block (default safe behavior)
3. If merging:
   • Dismisses any prior CHANGES_REQUESTED reviews from Aira
   • Resolves all review conversation threads
   • Posts a merge decision comment with the AI's reasoning. If violations were allowed, the comment tags the PR author with a follow-up checklist (specific file:line, what to fix, how to fix it)
   • Posts an APPROVE review
   • Squash merges the PR
4. Logs everything in the audit trail and fires an action.auto_merged webhook

Auto-Merge Policy

Go to Dashboard → Integrations → GitHub and click Create auto-merge policy. This takes you to the policy creation page with everything pre-filled — just review the prompt and save.

The policy supports AI mode (single model) or Consensus mode (multiple models vote). Write your rules in plain language:

You are deciding whether a PR can be auto-merged despite having violations.

Rules:
- ALLOW merge if all violations are: typos, formatting, missing translations,
  lint warnings, naming conventions, missing JSDoc comments
- BLOCK merge if any violation involves: hardcoded secrets, API keys,
  SQL injection, PII in logs, missing auth guards, raw database queries,
  payment-related code without validation

Respond with "allow" if the PR is safe to merge, or "deny" if any
violation is too risky. Explain your reasoning.

When the AI allows a merge despite violations, it generates a follow-up comment tagging the PR author with a checklist: which files and lines to fix, what's wrong, and how to fix it — including code examples.

Merge Method

The default merge method is squash. To change it, update your organization settings via the API.

Supported methods: squash (default), merge, rebase.

Safety Guards

Auto-merge will not trigger when:

• The github_auto_merge flag is disabled
• Violations exist and no auto-merge policy is configured
• The auto-merge policy AI decides to block
• The PR has merge conflicts
• The PR is already closed or merged

Self-Hosted Setup

Self-hosted customers need to create their own GitHub App:

1. Go to your GitHub org → Settings → Developer settings → GitHub Apps → New GitHub App
2. Set the webhook URL to https://YOUR_DOMAIN/api/v1/webhooks/github
3. Set permissions: Pull requests (read/write), Contents (read), Checks (read/write)
4. Subscribe to events: Pull request, Installation
5. Generate a private key and add to your .env:

GITHUB_APP_ID=your_app_id
GITHUB_APP_PRIVATE_KEY=base64_encoded_private_key
GITHUB_WEBHOOK_SECRET=your_webhook_secret
ENABLE_GITHUB_CODE_GOVERNANCE=true
ENABLE_GITHUB_AUTO_MERGE=true  # optional

Troubleshooting

PRs not being scanned:

• Verify the GitHub App is installed on the repository
• Verify the installation is linked to your Aira org
• Check that github_code_governance flag is enabled

Auto-merge not working:

• Verify github_auto_merge flag is enabled
• Check the PR is mergeable (no merge conflicts)
• If violations exist, verify an auto-merge policy is configured
• Check GitHub App permissions include Contents (read/write) — required for merging
• If branch protection requires conversation resolution, Aira resolves threads automatically — ensure the app has permission
• Check API logs: docker compose logs api | grep auto_merge

Review not appearing on PR:

• Check GitHub App permissions include Pull requests (read/write)
• Check API logs for review posting errors

Policy references showing as links (e.g. clicking "policy 2" opens PR 2):

• This is fixed in the latest version. The AI uses "policy 2" instead of "#2" to prevent GitHub auto-linking