Skip to main content

​
Policy Basics

Policies are rules that MergeGuide uses to analyze code changes. This guide covers the fundamentals of how policies work.

​
What is a Policy?

A policy is a declarative rule that:
  1. Identifies specific code patterns or behaviors
  2. Evaluates whether those patterns are acceptable
  3. Reports violations with actionable feedback

​
Policy Structure

Every policy has these components: 
id: no-hardcoded-secrets
name: No Hardcoded Secrets
description: Detect secrets, API keys, and credentials in code
severity: error
enabled: true

patterns:
  - type: regex
    value: "(api[_-]?key|secret|password)\\s*[=:]\\s*['\"][^'\"]{8,}['\"]"
    message: "Potential hardcoded secret detected"

suggestions:
  - "Move this value to an environment variable"
  - "Use a secrets manager like AWS Secrets Manager or HashiCorp Vault"

​
Core Concepts

​
Policy ID

A unique identifier for the policy: 
id: no-sql-injection
  • Lowercase with hyphens
  • Must be unique within your organization
  • Used in CLI commands and ignore comments

​
Severity Levels

LevelMeaningBehavior
errorCritical violationBlocks merges/commits
warningPotential issueReported but allowed
infoSuggestionInformational only

​
Enabled State

Control whether a policy is active: 
enabled: true   # Policy runs
enabled: false  # Policy skipped

​
Patterns

Patterns define what code to flag: 
patterns:
  - type: regex
    value: "eval\\s*\\("
    message: "eval() usage detected"
Pattern types:
  • regex - Regular expression matching
  • ast - Abstract Syntax Tree analysis
  • semantic - Language-aware analysis

​
Your First Policy

Let’s create a simple policy that detects console.log statements: 
id: no-console-log
name: No Console Log
description: Prevent console.log in production code
severity: warning
enabled: true

patterns:
  - type: regex
    value: "console\\.log\\s*\\("
    message: "console.log detected"

suggestions:
  - "Remove this console.log before committing"
  - "Use a proper logging library instead"

ignore:
  - "**/*.test.ts"
  - "**/*.spec.ts"

​
Testing Your Policy

Test policies before deploying: 
# Validate policy syntax
mergeguide policies validate ./my-policy.yaml

# Test against specific file
mergeguide check --policy ./my-policy.yaml src/file.ts

# Test against sample code
echo "console.log('test');" | mergeguide check --stdin --policy ./my-policy.yaml

​
Policy Inheritance

Policies can extend built-in policies: 
extends: no-hardcoded-secrets

# Override settings
severity: warning

# Add additional patterns
patterns:
  - type: regex
    value: "my_company_key_\\w+"

​
Next Steps