Dynamic Labels

← Back to Features

Use automated labeling to create dynamic, context-aware review policies. MergeGuard reads labels as signals—you control how they’re generated.

Overview

MergeGuard uses labels as signals to make policy decisions on pull requests.

Instead of analyzing your code directly, MergeGuard consumes labels that already exist on the PR and evaluates them against your configured policies. This keeps MergeGuard deterministic, secure, and fully aligned with GitHub’s native workflow.

Your workflows & tools → PR labels → MergeGuard policies → merge decision

MergeGuard does not generate labels itself. It only reads them and applies your review rules accordingly.

Why Labels?

Labels are:

  • Native to GitHub — visible, auditable, and familiar to every developer
  • Easy to produce — from workflows, bots, or tools you already use
  • Stable inputs — for deterministic policy evaluation

By using labels, MergeGuard avoids:

  • ❌ Reading your source code
  • ❌ Running AI models
  • ❌ Managing secrets for external analysis
  • ❌ Introducing non-deterministic behavior

MergeGuard doesn’t enforce a fixed label schema, but these conventions are recommended for predictable behavior.

PR Size / Complexity

mg:size/XS
mg:size/S
mg:size/M
mg:size/L
mg:size/XL

Used to express how large or complex a change is, based on heuristics or AI analysis.

Risk Level

mg:risk/low
mg:risk/medium
mg:risk/high

Indicates blast radius or sensitivity (infra, schema, security, payments, etc.).

Area Signals (Optional)

mg:area/infra
mg:area/schema
mg:area/security
mg:area/payments

Useful for policies that escalate reviews when specific areas are touched.

How to Generate Labels

You can generate labels using GitHub workflows or existing AI review tools. MergeGuard works with both approaches.

Option 1: GitHub Workflows (Heuristics)

A common approach is to use a GitHub Action that labels PRs based on:

  • Number of files changed
  • Lines added/removed (churn)
  • Directories or paths touched

Example with srvaroa/labeler

A popular and flexible option is srvaroa/labeler, which runs entirely inside your repository.

Workflow file (.github/workflows/labeler.yml):

name: PR Labeler
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: srvaroa/labeler@v1
        with:
          config_path: .github/labeler.yml

Configuration (.github/labeler.yml):

labels:
  - name: mg:size/XL
    conditions:
      any:
        - size.above: 2000
        - files.above: 60

  - name: mg:size/L
    conditions:
      size.above: 800

  - name: mg:size/M
    conditions:
      size.above: 250

  - name: mg:size/S
    conditions:
      size.above: 50

  - name: mg:risk/high
    conditions:
      any:
        - files:
            patterns:
              - "infra/**"
              - "terraform/**"
              - "schema/**"
              - "migrations/**"

Benefits:

  • ✅ Runs on PR events
  • ✅ Applies labels automatically
  • ✅ Requires no external services
  • ✅ All analysis stays inside GitHub

Option 2: AI Code Review Tools

If your organization uses AI review tools, you can configure them to apply labels instead of (or in addition to) enforcing rules directly.

Many AI review tools can analyze PRs for complexity, risk, or architectural impact and add labels based on their findings.

CodeRabbit

CodeRabbit provides AI-powered code reviews and can automatically label PRs based on analysis.

Configure CodeRabbit to add labels like mg:size/L or mg:risk/high based on its assessment. See the CodeRabbit documentation for configuration options.

Qodo (formerly CodiumAI)

Qodo offers AI-assisted code review and can be configured to label PRs based on complexity analysis.

Check the Qodo documentation for details on automatic labeling configuration.

Other AI Tools

Any AI review tool that can add GitHub labels can integrate with MergeGuard. Configure your tool to apply labels following the recommended patterns above, and MergeGuard will consume them.

Benefits of AI-based labeling:

  • ✅ Deeper semantic analysis
  • ✅ Risk detection beyond simple heuristics
  • ✅ Uses your existing tool investments
  • ✅ Clean separation: AI analyzes, MergeGuard enforces

Configuring MergeGuard to Use Labels

Once labels are on the PR, configure rules to consume them:

Scale Approvals by Size

rules:
  - name: "Extra-large changes"
    priority: 40
    if:
      labels:
        include: ["mg:size/XL"]
    require:
      approvals: 4

  - name: "Large changes"
    priority: 50
    if:
      labels:
        include: ["mg:size/L"]
    require:
      approvals: 3

  - name: "Medium changes"
    priority: 60
    if:
      labels:
        include: ["mg:size/M"]
    require:
      approvals: 2

  - name: "Small changes"
    priority: 70
    if:
      labels:
        include: ["mg:size/S", "mg:size/XS"]
    require:
      approvals: 1

Escalate by Risk

rules:
  - name: "High-risk escalation"
    priority: 20
    if:
      labels:
        include: ["mg:risk/high"]
    require:
      approvals: 3
      teams:
        - "security-team"
        - "platform-team"

  - name: "Medium-risk review"
    priority: 30
    if:
      labels:
        include: ["mg:risk/medium"]
    require:
      approvals: 2

Combine Size and Risk

rules:
  - name: "Large high-risk changes"
    priority: 10
    if:
      labels:
        include: ["mg:size/L", "mg:size/XL"]
      labels:
        include: ["mg:risk/high"]
    require:
      approvals: 4
      teams:
        - "security-team"
        - "engineering-leads"

Best Practices

Use Consistent Prefixes

Namespace your labels (e.g., mg:) to avoid conflicts with other labels:

mg:size/L      ✅ Clear MergeGuard signal
size-large     ❌ May conflict with other uses

Combine with Path-Based Rules

Labels complement path-based conditions—use both:

- name: "High-risk infrastructure"
  if:
    paths: ["infra/**"]
    labels:
      include: ["mg:risk/high"]
  require:
    approvals: 4

Document Label Meanings

Create a reference in your repository for what each label means and how it’s generated.

Start Simple

Begin with size labels and expand to risk/area labels as needed:

  1. Week 1: Add size labels via workflow
  2. Week 2: Configure MergeGuard rules
  3. Week 3: Add risk labels for critical paths
  4. Week 4: Integrate AI tools if desired

Key Principles

Principle What It Means
Labels are inputs MergeGuard consumes labels, never generates them
Customer-owned generation You control how labels are created
Deterministic evaluation Same labels = same policy decision
AI is optional Works with simple heuristics or advanced AI
Nothing leaves GitHub All data stays in your environment
← Back to Features Next: Conditional Approvals →