Branch Cleanup Rules & Lifecycle

Keeping our repository clean and manageable is essential for developer productivity, faster CI/CD pipelines, and reducing confusion caused by abandoned or stale branches. This document explains how our Branch Cleanup Automation works, its lifecycle, rules, and what the team must review before real deletions are enabled.

Overview

We maintain an automated cleanup workflow that regularly reviews branches, checks their status, logs the findings, and (optionally) deletes them.

Right now, if the workflow is running in dry run mode, which means:

• It simulates deletions
• It logs which branches would be removed
• It does not actually delete anything until we flip the switch

This article outlines the rules, safety checks, lifecycle, and what needs to be done before enabling real deletions.

1. Why Branch Cleanup Matters

A growing number of stale branches causes:

• Slower and longer git fetch/clone times
• Difficulty tracking what work is active or abandoned
• Higher risk of re-introducing outdated work
• A cluttered repository affecting CI workflows

Automated cleanup helps enforce a healthy repository and avoids long-term accumulation of unmaintained branches.

2. Branch Cleanup Lifecycle

Below is the lifecycle used by the cleanup workflow:

Step 1 — Scan Repository

The workflow pulls all branches from GitHub and evaluates their metadata:

• Last commit date
• Whether they’re merged into main
• Author
• Protection status
• Whether they match naming conventions

Step 2 — Apply Cleanup Rules

Detected branches are evaluated against our cleanup policy:

1. Protected branches are always ignored
   • main, master, or any branch with GitHub protection rules enabled
2. Active branches are never deleted
   • Recent commits
   • Currently referenced in an open PR
3. Merged branches are eligible for cleanup
   • If completely merged to main
   • No active PR
   • Older than 30 days
4. Stale branches are candidates for review
   • No updates
   • Not merged
   • No associated PR
   • Older than 30 days

Step 3 — Log Sheet Update

All findings are written into our tracking sheet:

Branch Cleanup Log Sheet
https://docs.google.com/spreadsheets/d/1noG98sqMXmn4SX1rmSug8_HfroKjSGCIY8PZqUFHyiA/edit?usp=sharing

Fields typically include:

• Branch Name
• Owner
• Branch SHA
• Days InActive
• IsDeleted
• DryRun
• IsPR

Step 4 — Dry-Run Simulation

Before activating real deletes:

• The workflow runs with dryRun: true
• It prints which branches would be deleted
• Nothing is modified in the repo

This allows the team to safely review the results.

Step 5 — Team Verification

Deletion only begins after:

• The team reviews the log sheet
• The list of branches is validated
• Any important branches are flagged for exemption
• Everyone confirms the cleanup is safe to run

Step 6 — Real Deletion (after approval)

Once approved:

• dryRun is flipped from true → false
• Cleanup workflow performs actual branch deletions
• The first 3 runs are monitored to ensure no unintended removals

3. Cleanup Rules

Rule 1 — Protected Branches

These branches are never touched:

• main
• master
• production
• release
• Any branch with GitHub branch protection rules

Rule 2 — Merged Branch Deletion

A branch qualifies for deletion if:

• Fully merged into main
• No active PR
• Last commit > 30 days old

Rule 3 — Stale Branch Deletion

A branch is stale if:

• No commits for 30+ days
• No open PR

Rule 4 — Naming-Convention Safety

Branches matching patterns like:

• release/*
• deploy/*

are excluded unless manually confirmed.

Rule 5 — Audit Logging

Every action (simulated or real) is logged into the cleanup sheet for review.

4. Activation Plan

Before switching to real deletion:

1. Team reviews the log sheet

Check if the branches marked for deletion are safe to remove.

2. Confirm no important branches are accidentally flagged

Developers may tag a branch as keep if needed.

3. Flip the workflow parameter

Change:

dryRun: true

to:

dryRun: false

4. Monitor the first three runs

If anything unexpected appears, we revert or adjust rules.

5. Safety Considerations

No Personal Data

Branch cleanup doesn’t involve any user-related data.

Low Risk

Deleting old branches doesn’t affect deployed code or production environments. All branches must already be merged or clearly inactive before deletion.

Checks in Place

• Protected branches ignored
• PR-linked branches ignored
• Log sheet reviewed
• Dry-run validation
• Post-activation monitoring