Branch Protection Configuration Fix Recommendations for Apiary Repository

branch-protection-fix-recommendations.md

Branch Protection Configuration Fix for Apiary Repository

Problem Summary

The branch protection rule "Changes must be made through a pull request" is incorrectly being applied to PR feature branches (e.g., HDC-1960). This rule should only protect the main branches (main and release), not feature branches used for pull requests.

Current Behavior

• Pushing to feature branches like HDC-1960 triggers "Bypassed rule violations" warning
• The push succeeds because of admin override permissions, but this indicates misconfiguration
• Feature branches should allow direct pushes as part of the normal PR workflow

Root Cause

Branch protection rules are configured in GitHub's UI (Settings → Branches), not in repository files. The current configuration likely:

1. Applies protection to all branches (including feature branches), OR
2. Uses a pattern that matches feature branch naming conventions (e.g., HDC-*), OR
3. Lacks proper exclusions for PR/feature branches

Recommended Solution

Option 1: Protect Only Specific Branches (RECOMMENDED)

Configuration:

• Create separate branch protection rules for:
  • main (production branch)
  • release (staging branch)
• Do NOT apply protection to feature branches

Steps:

1. Navigate to: https://github.com/Honeybee-Health/apiary/settings/branches
2. Review existing rules
3. Ensure rules only target main and release
4. Remove or modify any rules that apply to feature branches

Settings for main branch:

• ✅ Require a pull request before merging
• ✅ Require approvals (configure as needed)
• ✅ Require status checks to pass before merging
• ✅ Require branches to be up to date before merging
• ✅ Include administrators
• ❌ Do NOT allow force pushes
• ❌ Do NOT allow deletions

Settings for release branch:

• ✅ Require a pull request before merging
• ✅ Require approvals (may be less strict than main)
• ✅ Require status checks to pass before merging
• ✅ Require branches to be up to date before merging
• ✅ Include administrators
• ⚠️ Consider allowing force pushes if needed for hotfixes (with caution)

Option 2: Pattern-Based Rules with Exclusions

If you need pattern-based protection, configure exclusions:

Protected Pattern: * (all branches)

Exclusions:

• HDC-* (Hive feature branches)
• KEEP-* (Keeper feature branches)
• PZR-* (Partners feature branches)
• DEVOPS-* (DevOps feature branches)
• COL-* (Colony feature branches)
• DASH-* (Dashboard feature branches)

Note: GitHub branch protection doesn't support wildcard exclusions directly. You'll need to:

1. Use specific branch name rules instead, OR
2. Apply protection only to main and release explicitly

Option 3: Allow Pushes to Branches with Open PRs

If you must protect all branches:

• Enable "Allow force pushes" for feature branches (not recommended)
• Use GitHub Actions to automatically allow pushes to branches with open PRs (complex)

Feature Branch Naming Conventions

Based on codebase analysis, feature branches follow these patterns:

• HDC-* - Hive-related tickets
• KEEP-* - Keeper-related tickets
• PZR-* - Partners-related tickets
• DEVOPS-* - DevOps-related tickets
• COL-* - Colony-related tickets
• DASH-* - Dashboard-related tickets

These branches are used for pull requests and should allow direct pushes.

Verification Steps

After updating branch protection:

1. Test feature branch push:

   git checkout -b test-branch-protection
   git commit --allow-empty -m "Test branch protection"
   git push origin test-branch-protection

   • Should NOT show "bypassed rule violations"
   • Should succeed without warnings

2. Test protected branch push:

   git checkout main
   git commit --allow-empty -m "Test main protection"
   git push origin main

   • Should be blocked (unless you have admin override)
   • Should require PR workflow

3. Verify PR workflow:

   • Create PR from feature branch to main
   • Ensure PR requires approvals and status checks
   • Verify merge is blocked until requirements are met

Current Workflow Context

The repository uses:

• Mono-repo structure with multiple Rails apps
• PR-based workflow with feature branches
• Automated CI/CD via GitHub Actions
• JIRA integration for ticket tracking
• Environment deployments based on branch (main → production, release → staging)

Branch protection should support this workflow, not hinder it.

Action Items

1. ✅ Review current branch protection rules in GitHub Settings
2. ✅ Update rules to only protect main and release
3. ✅ Remove any rules applying to feature branch patterns
4. ✅ Test pushing to a feature branch (should work without warnings)
5. ✅ Verify main and release are still properly protected
6. ✅ Document the final configuration for team reference

Related Files

• .github/workflows/build.yml - CI/CD workflow
• .github/workflows/cleanup-pr-env.yml - PR environment cleanup
• .github/PULL_REQUEST_TEMPLATE/ - PR templates

Additional Notes

• Branch protection rules are repository-level settings, not code
• Changes require repository admin access
• Consider documenting branch protection policy in repository README or wiki
• The "bypassed rule violations" message indicates admin override, which should only be used in emergencies