Automating Folder Structure Validation with GitHub Actions and Bash

Mladen Radivojevic

Mladen Radivojevic

— 2 min read
Automating Folder Structure Validation with GitHub Actions and Bash
Folders

Introduction

Maintaining a consistent folder structure in a monorepo(or any repo) can be critical for collaboration and scaling. For instance, you may require every package in a packages folder to have a tests/ folder, a README.md, and a package.json. Ensuring this structure manually can be tedious and error-prone.

In this post, we’ll see how to automate this validation using a combination of a Bash script and GitHub Actions. This approach ensures that every pull request (PR) adheres to the required structure before merging, streamlining your workflow and reducing human error.

Defining the Problem

Our objective is to:

  • Iterate through all directories in a packages folder.
  • Validate that each directory contains:
    • A tests/ folder.
    • A README.md file.
    • A package.json file.

If any of these elements are missing, the workflow should fail and provide details about the discrepancies.

Step 1: Creating the Bash Script

The following Bash script performs the folder structure validation:

#!/bin/bash

# Define the target directory
target_dir="packages"

# Initialize a flag to track validation status
is_valid=true

# Iterate over all directories in the target folder
for dir in "$target_dir"/*/; do
  # Extract the directory name
  dir_name=$(basename "$dir")

  echo "Checking structure for package: $dir_name"

  # Check for the required files and folders
  if [[ ! -d "$dir/tests" ]]; then
    echo "Error: Missing 'tests/' folder in $dir_name"
    is_valid=false
  fi

  if [[ ! -f "$dir/README.md" ]]; then
    echo "Error: Missing 'README.md' in $dir_name"
    is_valid=false
  fi

  if [[ ! -f "$dir/package.json" ]]; then
    echo "Error: Missing 'package.json' in $dir_name"
    is_valid=false
  fi

done

# Exit with appropriate status
if [ "$is_valid" = false ]; then
  echo "Validation failed. Fix the errors above."
  exit 1
else
  echo "All packages passed validation."
  exit 0
fi

Save this script in your repository as validate-structure.sh and make it executable:

chmod +x validate-structure.sh

Step 2: Integrating with GitHub Actions

Create a GitHub Actions workflow to execute the validation script automatically on pull requests.

Workflow YAML File

Save the following as .github/workflows/validate-structure.yml:

name: Validate Folder Structure

on:
  pull_request:
    branches:
      - main

jobs:
  validate-structure:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

#No need to do this each time, but can have it as a small lifeguard
      - name: Set up permissions
        run: chmod +x ./validate-structure.sh

      - name: Run validation script
        run: ./validate-structure.sh

Demonstration

Example Repository Structure

Here’s an example of a valid packages folder:

packages/
  package-a/
    tests/
    README.md
    package.json
  package-b/
    tests/
    README.md
    package.json

A Failing Example

Suppose package-a is missing a tests/ folder. When a PR is opened, the workflow will run and produce logs like this:

Checking structure for package: package-a
Error: Missing 'tests/' folder in package-a
Validation failed. Fix the errors above.

This feedback allows developers to correct the issue before merging.

Conclusion

By combining Bash scripting with GitHub Actions, you can automate folder structure validation and enforce consistency in your projects. This ensures that your codebase remains organized and adheres to agreed-upon standards, ultimately saving time and avoiding potential pitfalls.

Feel free to adapt the script and workflow to fit your specific requirements. Happy automating!

Read more