testsAndMisc/linux_configuration/.github/BRANCH_PROTECTION.md

Branch Protection and Pre-Merge Checks

This repository uses GitHub Actions to ensure code quality before merging to main or master branches.

Required Checks

Shell Script Linting

The Shell Script Linting workflow automatically runs on:

• Pull requests targeting main or master branches (including from forks)
• Direct pushes to main or master branches

This workflow checks:

• Shell script syntax with shellcheck
• Code formatting with shfmt (2-space indentation, no tabs)
• Optional checks: checkbashisms, syntax validation

Enabling Branch Protection

To make the shell linting check required before merging PRs, follow these steps:

1. Go to repository Settings → Branches
2. Click Add rule or edit existing rule for main/master
3. Configure the following settings:
   • ✅ Require a pull request before merging
   • ✅ Require status checks to pass before merging
     • Search for and select: Lint Shell Scripts
   • ✅ Require branches to be up to date before merging (recommended)
   • ✅ Do not allow bypassing the above settings (recommended)
4. Click Create or Save changes

Running Checks Locally

Before pushing changes, run the linting script locally to catch issues early:

bash scripts/meta/shell_check.sh

This will:

• Install required linters on Arch Linux (if needed)
• Check all shell scripts in the repository
• Report any formatting or syntax issues

To auto-fix formatting issues:

# Install shfmt if not already installed
# On Arch: sudo pacman -S shfmt
# Or download from: https://github.com/mvdan/sh/releases

# Fix formatting in-place
find . -name "*.sh" -type f | xargs shfmt -w -i 2 -ci -sr -s

What Gets Checked

The workflow validates shell scripts with these extensions or shebangs:

• *.sh, *.bash, *.zsh files
• Executable files with shell shebangs (#!/bin/bash, #!/bin/sh, etc.)

Troubleshooting

If the check fails on your PR:

1. Review the workflow logs to see which files failed
2. Run bash scripts/meta/shell_check.sh locally to reproduce
3. Fix the issues (usually formatting with shfmt -w -i 2 -ci -sr -s)
4. Commit and push the fixes

The workflow will automatically re-run on new commits to the PR.