Add workflow to validate branch ancestry

[jake-mahon-netwrix]

Summary

This workflow prevents branches containing old git history (from before repository re-initialization) from being merged into dev/main, protecting against re-introduction of sensitive data.

---

How It Works

The workflow validates branch ancestry by:

1. Checking ALL root commits of every pushed branch
2. Comparing against valid initialization commits (currently: 97e73c5)
3. Failing if ANY root is invalid with clear error message and fix instructions
4. Passing if all roots are valid

This handles edge cases like merged branches with multiple root commits.

---

What This Blocks

Branches containing pre-initialization git history that include sensitive data removed during repository cleanup.

---

Configuration After Merge

⚠️ REQUIRED: Branch Protection Setup

The workflow creates a status check named Validate Clean History but does NOT block merges until you configure branch protection rules.

For dev branch:

1. Settings → Branches → Edit dev protection rule
2. Under "Require status checks to pass before merging"
3. Add status check: Validate Clean History
4. Save

For main branch:

1. Settings → Branches → Edit main protection rule
2. Under "Require status checks to pass before merging"
3. Add status check: Validate Clean History
4. Save

Note: The check must run successfully at least once before it appears in the dropdown.

---

No Other Configuration Needed

✅ No secrets or tokens to configure
✅ No repository variables to set
✅ Uses built-in GITHUB_TOKEN automatically
✅ Works immediately upon merge

Only action: Configure branch protection rules ☝️

---

Security Features

• Multi-root detection: Handles merged branches correctly
• Minimal permissions: Only reads (contents:read, pull-requests:read)
• Clear error messages: Developers get step-by-step fix instructions
• No external dependencies: Pure git commands + GitHub Actions
• Timeout protection: 10-minute limit prevents runaway workflows

---

Future Maintenance

If repository is re-initialized again:

1. Edit .github/workflows/validate-branch-history.yml
2. Add new root commit to VALID_ROOTS array (line 32)
3. Commit and push

---

Testing Plan

After merge:

1. Configure branch protection rules on dev and main
2. Verify branches with old history are blocked from merging
3. Verify new branches from dev/main pass the check

---

Review Notes

• This is a clean, single-commit PR
• Commit message contains full technical documentation
• No follow-up PRs required for core functionality
• Documentation updates can be added separately if desired

[hilram7]

Hi @jake-mahon-netwrix, thank you for creating this much-needed workflow. I just want to double-check that it is ready since I see there have been a few rounds of Claude Code Review for this PR, and the last one shows Status: Conditional Approval.

Once you confirm no more changes are needed, I will approve.

[github-actions]

Pull Request Review - Validate Branch History Workflow

I've reviewed PR #40 and here is my comprehensive feedback:

---

Strengths

1. Security-First Design

   • Excellent purpose: Prevents reintroduction of sensitive data through old git history
   • Minimal permissions (contents:read, pull-requests:read) follow principle of least privilege
   • Built-in timeout protection (10 minutes) prevents runaway workflows
   • No external dependencies reduces attack surface

2. Robust Implementation

   • Multi-root detection: Correctly handles merged branches with multiple root commits
   • Clear validation logic with proper error handling
   • Comprehensive developer-facing error messages with step-by-step fix instructions

3. Documentation & User Experience

   • Excellent PR description with clear setup instructions
   • Helpful error messages guide developers through remediation
   • Clear contact reference for assistance

---

Issues & Recommendations

1. Workflow Name vs Status Check Name Mismatch

Location: Line 1 and Line 20

Issue:

• Workflow name: "Validate Branch History"
• Job name: "Validate Clean History"

The status check that appears in GitHub will be named after the job name, not the workflow name. Your PR description references "Validate Clean History" which is correct.

Recommendation: Rename the workflow to "Validate Clean History" to match the job name for consistency.

2. Error Message Contact Variable

Location: Line 15-16 and Line 91

The GitHub team reference format should include the @ symbol for proper mentions.

Recommendation: Update to: SECURITY_CONTACT: '@netwrix/docs-admins'

3. Trigger Configuration Note

Location: Lines 3-13

The workflow creates the status check but doesn't enforce blocking until branch protection is configured. Consider adding a comment in the workflow file to clarify this.

Recommendation: Add a comment at the top of the workflow explaining that branch protection rules must be configured separately to enforce blocking.

---

Code Quality Assessment

Category	Rating	Notes
Security	5/5	Excellent minimal permissions, no credential exposure
Correctness	4/5	Logic is sound; minor improvement needed for contact mention
Maintainability	5/5	Clear code, excellent comments, easy to update VALID_ROOTS
Documentation	5/5	Outstanding PR description and error messages
Error Handling	5/5	Comprehensive with actionable remediation steps

---

Pre-Merge Checklist

• Fix the @ prefix for SECURITY_CONTACT mention
• Consider renaming workflow to "Validate Clean History" for consistency
• Verify that job name "Validate Clean History" is what you want for branch protection
• Confirm netwrix/docs-admins team exists and can be mentioned

---

Performance & Security

• Performance: Git operations are efficient; timeout prevents issues
• Security: No secrets exposed, minimal permissions
• Test Coverage: Integration testing required post-merge as documented

---

Overall Assessment

This is a well-crafted security workflow with excellent documentation. The implementation correctly handles edge cases (merged branches) and provides clear user guidance. The issues identified are minor and primarily related to naming consistency and formatting of the team mention.

Recommendation: Approve with minor changes (contact formatting and name consistency)

---

Post-Merge Actions

1. Configure branch protection on dev and main branches
2. Add status check: "Validate Clean History" (job name, not workflow name)
3. Test with a branch containing old history
4. Test with a fresh branch from dev/main

Great work on this security-focused workflow!

[jake-mahon-netwrix]

To test this new workflow and branch protection rule, we need to recreate the scenario of someone attempting to merge the old Git history into the fresh repository. So we're going to make two private copies, one of the fresh repository, one of the archived one. We're going to add this workflow and branch protection rule to the private copy of the fresh repo. And then we're going to attempt to merge the private copy of the old archived one into the new one and see if it works. And if it does, and we test a few other edge cases and it works, then we'll come back here and merge this branch.