VCS Guardrails

Version control system (VCS) best practices and security policies for repositories

Overview

This policy plugin enforces version control system security standards, focusing on branch protection rules that prevent unauthorized or risky changes to critical branches. Branch protection is a fundamental security control that ensures code review, testing, and approval processes are followed before changes reach production. Development teams using GitHub (or similar VCS platforms) should use this policy to enforce consistent protection rules across repositories.

Policies

This plugin provides the following policies (use include to select a subset):

Branch Protection Policies

These policies enforce specific branch protection requirements. Use include to select which policies to enforce.

Repository Settings Policies

Required Data

This policy reads from the following Component JSON paths:

Note: This policy requires a VCS collector (such as github) that populates the .vcs data.

Installation

Add to your lunar-config.yml:

policies:
  # Run all policies (default - enforces all branch protection and repository settings)
  - uses: github://earthly/lunar-lib/policies/vcs@v1.0.0
    on: "domain:your-domain"  # Or use tags like production, critical
    enforcement: report-pr    # Options: draft, score, report-pr, block-pr, block-release, block-pr-and-release
    with:
      min_approvals: 2
      allowed_merge_strategies: "squash"
      # required_default_branch: "main"

  # Use include to run only specific policies
  - uses: github://earthly/lunar-lib/policies/vcs@v1.0.0
    include:
      - branch-protection-enabled
      - require-pull-request
      - minimum-approvals
      - disallow-force-push
      - require-signed-commits
      - require-private
    on: "domain:your-domain"
    enforcement: block-pr
    with:
      min_approvals: 2

  # Run only repository settings policies
  - uses: github://earthly/lunar-lib/policies/vcs@v1.0.0
    include:
      - require-private
      - require-default-branch
      - allowed-merge-strategies
    on: "domain:your-domain"
    enforcement: report-pr
    with:
      allowed_merge_strategies: "squash,rebase"

Examples

Passing Example - Production Repository

A production repository with strict security controls:

{
  "vcs": {
    "provider": "github",
    "visibility": "private",
    "default_branch": "main",
    "branch_protection": {
      "enabled": true,
      "branch": "main",
      "require_pr": true,
      "required_approvals": 2,
      "require_codeowner_review": true,
      "dismiss_stale_reviews": true,
      "require_status_checks": true,
      "require_branches_up_to_date": true,
      "allow_force_push": false,
      "allow_deletions": false,
      "require_linear_history": false,
      "require_signed_commits": true
    },
    "merge_strategies": {
      "allow_merge_commit": false,
      "allow_squash_merge": true,
      "allow_rebase_merge": false
    }
  }
}

With policy configuration using include to select desired checks:

include:
  - branch-protection-enabled
  - require-pull-request
  - minimum-approvals
  - require-codeowner-review
  - dismiss-stale-reviews
  - require-status-checks
  - require-branches-up-to-date
  - disallow-force-push
  - disallow-branch-deletion
  - require-signed-commits
  - require-private
  - require-default-branch
  - allowed-merge-strategies
with:
  min_approvals: 2
  allowed_merge_strategies: "squash"

This passes because all security controls match policy requirements.

Failing Example - Branch Protection Not Enabled

{
  "vcs": {
    "branch_protection": {
      "enabled": false,
      "branch": "main"
    }
  }
}

With policy configuration:

include:
  - branch-protection-enabled
  - minimum-approvals
with:
  min_approvals: 1

Failure messages:

• branch-protection-enabled: "Branch protection is not enabled on main"
• minimum-approvals: "Branch protection is not enabled"

Failing Example - Wrong Settings

{
  "vcs": {
    "visibility": "public",
    "default_branch": "master",
    "merge_strategies": {
      "allow_merge_commit": true,
      "allow_squash_merge": true,
      "allow_rebase_merge": false
    }
  }
}

With policy configuration:

include:
  - require-private
  - require-default-branch
  - allowed-merge-strategies
with:
  allowed_merge_strategies: "squash"
  # required_default_branch defaults to "main"

Failure messages:

• "Repository visibility is 'public', but policy requires 'private'"
• "Default branch is 'master', but policy requires 'main'"
• "Merge commits are enabled, but policy does not allow them (should be disabled)"

Remediation

Branch Protection Policies

When branch protection policies fail, configure branch protection rules in your repository settings:

1. GitHub: Navigate to your repository → Settings → Branches → Branch protection rules
2. Select your default branch (typically main or master) or create a new rule
3. Enable the required protection settings based on the policy failures:
   • Require pull request reviews before merging - Set the number of required approvals
   • Require review from Code Owners - Enable if codeowner review is required
   • Dismiss stale pull request approvals when new commits are pushed - Enable if required
   • Require status checks to pass before merging - Enable and select required checks
   • Require branches to be up to date before merging - Enable if required
   • Do not allow bypassing the above settings - Disable "Allow force pushes" and "Allow deletions"
   • Require linear history - Enable if required by policy
   • Require signed commits - Enable if required by policy
4. Save the branch protection rule
5. Re-run the Lunar collector and policy to verify compliance

Repository Settings Policies

When repository settings policies fail, update repository settings:

1. GitHub: Navigate to your repository → Settings
2. Update the relevant settings based on the policy failures:
   • Repository visibility (General section):
     • Change visibility to match policy requirements (Private or Public)
     • Note: Changing visibility may have security implications - consult your security team
   • Default branch (General section):
     • Rename your default branch if required (e.g., from master to main)
     • GitHub provides a "Rename branch" button in the repository settings
     • Update local clones and CI/CD configurations after renaming
   • Merge button (Pull Requests section):
     • Enable only the merge strategies listed in allowed_merge_strategies
     • Disable any strategies not in the allowed list
     • Example: If policy specifies "squash,rebase", enable those two and disable merge commits
3. Save the changes
4. Re-run the Lunar collector and policy to verify compliance