Skip to main content

Setting Up Branch Protection

Welcome to Ship Guard! 🎉 This guide will help you set up branch protection in under 5 minutes.

Why Branch Protection Matters​

Without branch protection:

  • ❌ Developers can still merge PRs even when Ship Guard reports errors
  • ❌ Your team's coding standards won't be enforced
  • ❌ The automated review becomes just a suggestion

With branch protection:

  • ✅ PRs with Ship Guard errors are blocked from merging
  • ✅ Your coding standards are automatically enforced
  • ✅ Only clean, compliant code reaches your main branch

How to Set Up Branch Protection​

  1. Navigate to Repository Settings

    • Go to your repository on GitHub
    • Click on "Settings" tab (you need admin/owner permissions)

  2. Access Branch Protection Rules

    • In the left sidebar, click "Branches"
    • Click "Add rule" or "Add branch protection rule"

  3. Configure the Rule

    • Branch name pattern: Enter main (or master if that's your default branch)
    • Require status checks to pass before merging: ✅ Check this box
    • Require branches to be up to date before merging: ✅ Check this box

  4. Add Ship Guard as Required Check

    • In the "Status checks" section, search for "Ship Guard"
    • ✅ Check the box next to "Ship Guard"
    • This ensures PRs cannot be merged if Ship Guard reports any errors

  5. Additional Recommended Settings

    ✅ Require a pull request before merging
    ✅ Require approvals (set to 1 or more as needed)
    ✅ Dismiss stale PR approvals when new commits are pushed
    ✅ Require review from code owners (if you have a CODEOWNERS file)

  6. Save the Rule

    • Click "Create" or "Save changes"

Visual Guide​

Here's what the branch protection settings should look like:

┌─────────────────────────────────────────────┐
│ Branch protection rule                      │
├─────────────────────────────────────────────┤
│ Branch name pattern: main                   │
│                                             │
│ ✅ Require a pull request before merging    │
│ ✅ Require status checks to pass before     │
│    merging                                  │
│   └─ ✅ Ship Guard                     │
│ ✅ Require branches to be up to date before │
│    merging                                  │
│ ✅ Require approvals: 1                     │
└─────────────────────────────────────────────┘

Testing Branch Protection​

After setting up branch protection, test it:

  1. Create a PR with code that triggers a Ship Guard error
  2. Try to merge the PR
  3. You should see: "Merging is blocked - Ship Guard has not passed"

Important Notes​

  • Admin permissions required: Only repository admins/owners can set up branch protection
  • Organization settings: If this is an organization repository, you might need organization admin permissions
  • Existing PRs: Branch protection only affects new PRs; existing PRs may need to be updated
  • Bypass permissions: Consider who can bypass branch protection (usually only admins)