GitHub Repository Best Practices

Automated scripts and documentation for applying GitHub repository best practices across personal and organization accounts.

🎯 What This Repository Provides

This repository contains battle-tested scripts and comprehensive documentation for:

✅ Standardizing default branch to main across all repositories
✅ Applying best practice settings (auto-delete branches, squash-only merges, etc.)
✅ Creating new repositories with all best practices automatically applied
✅ Bulk fixing existing repositories
✅ Organization-wide configuration management

📂 Repository Structure

.
├── scripts/
│   ├── apply-repo-settings.sh           # Apply best practices to a single repo
│   ├── gh-repo-create-with-defaults.sh  # Create new repo with all defaults
│   ├── rename-to-main.sh                # Bulk rename master → main
│   └── open-org-settings.sh             # Open all org settings pages
├── docs/
│   ├── repository-settings.md           # Complete settings guide with rationale
│   ├── repo-defaults-setup.md           # Setup guide for new repo defaults
│   ├── bulk-fix-guide.md                # Bulk operations guide
│   └── default-branch-setup.md          # Default branch standardization
└── README.md                            # This file

🚀 Quick Start

1. Clone This Repository

git clone https://github.com/YOUR-ORG/github-best-practices.git
cd github-best-practices

2. Apply Best Practices to a Repository

# Apply to a specific repo
./scripts/apply-repo-settings.sh owner/repo-name

# Or from within a repo directory
cd ~/path/to/your/repo
../github-best-practices/scripts/apply-repo-settings.sh

3. Create New Repository with Defaults

./scripts/gh-repo-create-with-defaults.sh my-new-repo --private

4. Rename All Repos to Use "main"

./scripts/rename-to-main.sh

📋 Best Practices Applied

Repository Settings

Setting	Value	Benefit
Default Branch	`main`	Industry standard, inclusive naming
Auto-delete head branches	✓	Keeps repo clean, reduces clutter
Allow auto-merge	✓	Enables automated PR workflows
Allow squash merging	✓ (only option)	Clean, linear history
Require linear history	✓	Prevents messy merge commits
Require conversation resolution	✓	Ensures all feedback addressed
Wiki	✗	Use README/docs instead
Projects	✗	Use GitHub Projects at org level

Branch Protection (Main Branch)

✓ Require pull request before merging
✓ Dismiss stale reviews when new commits pushed
✓ Require conversation resolution before merging
✗ Allow force pushes (for cleaner history)

📖 Documentation

For Detailed Guides, See:

Repository Settings - Complete settings reference with before/after comparison
Repo Defaults Setup - Configure defaults for future repositories
Bulk Fix Guide - Apply settings to multiple repositories
Default Branch Setup - Standardize to "main" across account and orgs

🛠️ Scripts Reference

`apply-repo-settings.sh`

Apply all best practice settings to a single repository.

Usage:
  ./scripts/apply-repo-settings.sh [owner/repo]
  
Examples:
  ./scripts/apply-repo-settings.sh myorg/myrepo
  cd ~/myrepo && ../scripts/apply-repo-settings.sh

What it does:

Auto-delete head branches: enabled
Auto-merge: enabled
Squash merging: only option
Linear history: required
Conversation resolution: required
Wiki & Projects: disabled
Branch protection: configured

`gh-repo-create-with-defaults.sh`

Create a new repository with all best practices automatically applied.

Usage:
  ./scripts/gh-repo-create-with-defaults.sh REPO_NAME [OPTIONS]
  
Examples:
  ./scripts/gh-repo-create-with-defaults.sh my-new-project --private
  ./scripts/gh-repo-create-with-defaults.sh my-org/new-service --public

What it does:

Creates repo with "main" as default branch
Applies all best practice settings
Configures branch protection
Ready to clone and use immediately

`rename-to-main.sh`

Bulk rename default branches from "master" to "main" across all repositories.

Usage:
  ./scripts/rename-to-main.sh
  
Interactive prompts:
  - Confirms before proceeding
  - Shows progress for each repo
  - Reports success/failure

What it does:

Scans all non-archived, non-fork repos
Identifies repos using "master"
Renames branches using GitHub API
Updates default branch setting

`open-org-settings.sh`

Open organization settings pages for manual configuration.

Usage:
  ./scripts/open-org-settings.sh

What it does:

Fetches all organizations you belong to
Opens repository defaults page for each org
Provides instructions for manual configuration

🔍 Verification Commands

Check Your Configuration

# Verify git is configured for "main"
git config --global --get init.defaultBranch

# List repos still using "master"
gh repo list YOUR-USERNAME --limit 1000 --json name,defaultBranchRef | \
  jq -r '.[] | select(.defaultBranchRef.name == "master") | .name'

# Check organization default branch settings
gh api user/orgs --jq '.[].login' | while read org; do
  echo "$org: $(gh api orgs/$org --jq '.default_repository_branch')"
done

# Verify a specific repo's settings
gh repo view OWNER/REPO --json \
  defaultBranchRef,deleteBranchOnMerge,hasWikiEnabled,hasProjectsEnabled

🎓 Why These Best Practices?

Default Branch: "main"

The tech community has moved from "master" to "main" to use more inclusive language and align with industry standards. GitHub uses "main" as default for all new accounts created after October 2020.

Auto-delete Head Branches

Prevents branch clutter and reduces confusion about which branches are active. After a PR is merged, the feature branch is no longer needed.

Squash Merging (Only Option)

Creates a clean, linear history by combining all commits from a PR into a single commit. Makes it easier to:

Understand project history
Revert changes if needed
Perform git bisect operations

Require Linear History

Prevents merge commits, keeping the main branch history clean and easy to follow. Every commit represents a complete feature or fix.

Conversation Resolution

Ensures all review comments are addressed before merging. Improves code quality and team communication.

Disable Wiki & Projects

Repository wikis and projects are often neglected and create duplicate sources of truth. Better alternatives:

Use docs/ folder or README for documentation
Use GitHub Projects at organization level for project management
Use Issues for task tracking

🔧 Customization

Modify Settings

Edit scripts/apply-repo-settings.sh to adjust settings:

# Example: Enable wiki
gh api -X PATCH repos/$REPO \
  -f has_wiki=true

Add Custom Settings

See the GitHub REST API documentation for all available settings:

📊 Real-World Results

From standardizing 61 repositories and 6 organizations:

Before:

Mixed "master" and "main" branches (42 repos using "master")
Inconsistent settings across repositories
Manual configuration for each new repo
Branch clutter from undeleted feature branches

After:

100% standardized on "main" (55 active repos)
Consistent best practices across all repos
Automated repo creation with defaults
Clean repository state with auto-deletion

Time Saved:

New repo setup: ~5 minutes → 30 seconds
Bulk operations: Manual → Automated
Branch cleanup: Manual → Automatic

🤝 Contributing

This repository represents best practices for GitHub repository management. To contribute:

Test changes in a personal fork first
Document the rationale for any new practices
Update relevant documentation in docs/
Ensure scripts are POSIX-compliant where possible

📝 License

These scripts are provided as-is for use in managing GitHub repositories. Feel free to adapt them to your organization's needs.

🆘 Troubleshooting

Issue: "Resource not accessible by integration"

Cause: Insufficient GitHub CLI permissions
Solution:

gh auth refresh -h github.com -s repo -s admin:org

Issue: Script fails on specific repo

Cause: Empty repository or protected branch rules
Solution:

Check if repo has any commits: gh repo view OWNER/REPO
Verify branch protection isn't blocking: gh api repos/OWNER/REPO/branches/main/protection

Issue: Organizations not updating

Cause: Need admin permissions
Solution: Contact org owner or verify permissions with:

gh api orgs/ORG-NAME/memberships/$(gh api user --jq .login)

📚 Additional Resources

Last Updated: June 2026
Maintained by: @restlessankyyy

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
scripts		scripts
README.md		README.md
REPO-DEFAULTS-QUICKREF.md		REPO-DEFAULTS-QUICKREF.md

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

GitHub Repository Best Practices

🎯 What This Repository Provides

📂 Repository Structure

🚀 Quick Start

1. Clone This Repository

2. Apply Best Practices to a Repository

3. Create New Repository with Defaults

4. Rename All Repos to Use "main"

📋 Best Practices Applied

Repository Settings

Branch Protection (Main Branch)

📖 Documentation

For Detailed Guides, See:

🛠️ Scripts Reference

apply-repo-settings.sh

gh-repo-create-with-defaults.sh

rename-to-main.sh

open-org-settings.sh

🔍 Verification Commands

Check Your Configuration

🎓 Why These Best Practices?

Default Branch: "main"

Auto-delete Head Branches

Squash Merging (Only Option)

Require Linear History

Conversation Resolution

Disable Wiki & Projects

🔧 Customization

Modify Settings

Add Custom Settings

📊 Real-World Results

🤝 Contributing

📝 License

🆘 Troubleshooting

Issue: "Resource not accessible by integration"

Issue: Script fails on specific repo

Issue: Organizations not updating

📚 Additional Resources

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`apply-repo-settings.sh`

`gh-repo-create-with-defaults.sh`

`rename-to-main.sh`

`open-org-settings.sh`