Home / Documentation / Management Scripts

Management Scripts

Easy-to-use scripts to enable/disable hooks and CI jobs, manage configuration, and customize enforcement.

Why Management Scripts?

Pre-commit hooks and CI jobs are powerful, but sometimes you need flexibility:

  • During development - Temporarily disable slow checks while iterating
  • Incremental adoption - Enable checks gradually as your codebase improves
  • Project-specific needs - Some checks may not apply to your project
  • Team onboarding - Help new team members understand what's running

Management scripts provide a simple, consistent interface to control these tools without manually editing YAML files.

setup-precommit.sh

📦 setup-precommit.sh

Purpose: One-command setup of all pre-commit hooks

What It Does:

  1. Installs pre-commit framework (if not installed)
  2. Copies .pre-commit-config.yaml to your project
  3. Installs all pre-commit hooks
  4. Installs commit-msg hook (for commit message validation)
  5. Runs hooks on all files (first-time setup)

Usage:

# Basic usage
./scripts/setup-precommit.sh

# Skip running on all files (faster)
./scripts/setup-precommit.sh --skip-all-files

# Verbose output
./scripts/setup-precommit.sh --verbose

💡 When to Use

Run this script once when:

  • Setting up Guardrails-AI in a new project
  • A new team member joins and needs pre-commit hooks
  • After cloning the repository on a new machine

Expected Output:

✓ Pre-commit framework installed
✓ Configuration file copied
✓ Pre-commit hooks installed
✓ Commit-msg hook installed
✓ Running hooks on all files...
  
All checks passed! ✓

Pre-commit setup complete!

manage-precommit-hooks.sh

🎛️ manage-precommit-hooks.sh

Purpose: Enable, disable, and configure individual pre-commit hooks

Available Commands:

  • list - Show all hooks and their status (enabled/disabled)
  • enable <hook-id> - Enable a specific hook
  • disable <hook-id> - Disable a specific hook
  • show <hook-id> - Display hook configuration details
  • status - Summary of enabled/disabled hooks

Usage Examples:

# List all hooks
./scripts/manage-precommit-hooks.sh list

# Output:
✓ trailing-whitespace (enabled)
✓ end-of-file-fixer (enabled)
✓ check-yaml (enabled)
✗ shellcheck (disabled)
✓ detect-secrets (enabled)
✗ pylint (disabled)

# Disable expensive checks during active development
./scripts/manage-precommit-hooks.sh disable shellcheck
./scripts/manage-precommit-hooks.sh disable pylint

# Re-enable before pushing
./scripts/manage-precommit-hooks.sh enable shellcheck
./scripts/manage-precommit-hooks.sh enable pylint

# Show detailed configuration
./scripts/manage-precommit-hooks.sh show detect-secrets

💡 Common Use Cases

  • Speed up commits during debugging: Disable slow linters like shellcheck or pylint
  • Legacy codebase: Disable failing hooks initially, fix issues, then re-enable
  • Specialized projects: Disable hooks that don't apply (e.g., Python hooks in a shell-only project)
  • Team alignment: Quickly see which hooks are active in the project

Hook Status Output:

# Running: ./scripts/manage-precommit-hooks.sh status

Pre-commit Hooks Status:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Enabled:  15 hooks
Disabled: 3 hooks
Total:    18 hooks

Disabled hooks:
  - shellcheck (temporarily disabled)
  - pylint (temporarily disabled)
  - mypy (not applicable to project)

manage-ci-jobs.sh

⚙️ manage-ci-jobs.sh

Purpose: Control which CI jobs run in GitHub Actions

Available Commands:

  • list - Show all workflows and jobs
  • enable <workflow> <job> - Enable a CI job
  • disable <workflow> <job> - Disable a CI job
  • show <workflow> <job> - Display job configuration
  • status <workflow> - Show workflow status

Usage Examples:

# List all workflows and their jobs
./scripts/manage-ci-jobs.sh list

# Output:
Workflow: ci.yaml
  ✓ lint (enabled)
  ✗ test (disabled - no tests yet)
  ✓ build (enabled)

Workflow: security-ci.yml
  ✓ gitleaks (enabled)
  ✓ trufflehog (enabled)
  ✓ bandit (enabled)
  ✓ semgrep (enabled)

# Disable test job until tests are written
./scripts/manage-ci-jobs.sh disable ci.yaml test

# Enable when tests are ready
./scripts/manage-ci-jobs.sh enable ci.yaml test

# Show detailed job configuration
./scripts/manage-ci-jobs.sh show security-ci.yml gitleaks

💡 Common Use Cases

  • New project: Disable test job until test suite exists
  • Reduce CI costs: Disable expensive jobs during heavy development
  • Debugging: Isolate which job is failing by disabling others
  • Specific branches: Configure different jobs for different branches

How It Works:

The script comments/uncomments job definitions in workflow files:

# Before disabling:
jobs:
  test:
    runs-on: ubuntu-latest
    steps: ...

# After disabling:
jobs:
  # test:
  #   runs-on: ubuntu-latest
  #   steps: ...

bootstrap-guardrails.sh

🚀 bootstrap-guardrails.sh

Purpose: Complete setup of Guardrails-AI infrastructure in one command

What It Does:

  1. Copies all template files to your project:
    • Pre-commit configuration
    • GitHub Actions workflows
    • Management scripts
    • Security scripts
    • Documentation
  2. Sets up directory structure
  3. Makes scripts executable
  4. Optionally runs setup-precommit.sh

Usage:

# From the Guardrails-AI repo
./template/bootstrap-guardrails.sh /path/to/your/project

# Or from your project directory
/path/to/Guardrails-AI/template/bootstrap-guardrails.sh .

# With options
./template/bootstrap-guardrails.sh /path/to/project --setup-hooks --verbose

💡 When to Use

Perfect for:

  • Brand new projects
  • Adding Guardrails-AI to existing projects
  • Standardizing multiple projects with same infrastructure

Files Copied:

your-project/
├── .pre-commit-config.yaml
├── .github/
│   └── workflows/
│       ├── ci.yaml
│       └── security-ci.yml
├── scripts/
│   ├── setup-precommit.sh
│   ├── manage-precommit-hooks.sh
│   ├── manage-ci-jobs.sh
│   └── validate-commit-msg.sh
└── docs/
    ├── PRECOMMIT.md
    └── CI_CD.md

Common Workflows

New Project Setup

# 1. Bootstrap everything
git clone https://github.com/christopherpaquin/Guardrails-AI .ai-guardrails
./.ai-guardrails/template/bootstrap-guardrails.sh . --setup-hooks

# 2. Verify installation
./scripts/manage-precommit-hooks.sh list
./scripts/manage-ci-jobs.sh list

# 3. Test pre-commit
echo "test" > test.txt
git add test.txt
git commit -m "test: verify pre-commit works"

# 4. Push and verify CI runs
git push origin main

Active Development

# Speed up commits by disabling slow checks
./scripts/manage-precommit-hooks.sh disable shellcheck
./scripts/manage-precommit-hooks.sh disable pylint
./scripts/manage-precommit-hooks.sh disable mypy

# Work on your changes...
# Make many commits quickly

# Before final push, re-enable everything
./scripts/manage-precommit-hooks.sh enable shellcheck
./scripts/manage-precommit-hooks.sh enable pylint
./scripts/manage-precommit-hooks.sh enable mypy

# Run on all changed files
pre-commit run --all-files

# Push when clean
git push origin feature-branch

Legacy Codebase Adoption

# 1. Install with most hooks disabled
./scripts/setup-precommit.sh

# 2. Disable hooks that would fail on existing code
./scripts/manage-precommit-hooks.sh disable trailing-whitespace
./scripts/manage-precommit-hooks.sh disable shellcheck
./scripts/manage-precommit-hooks.sh disable pylint

# 3. Keep critical security hooks enabled
./scripts/manage-precommit-hooks.sh enable detect-secrets
./scripts/manage-precommit-hooks.sh enable check-private-key

# 4. Gradually fix issues and re-enable hooks
# Fix trailing whitespace in one PR
find . -type f -exec sed -i 's/[[:space:]]*$//' {} \;
./scripts/manage-precommit-hooks.sh enable trailing-whitespace

# Fix shellcheck issues in next PR
# ... fix issues ...
./scripts/manage-precommit-hooks.sh enable shellcheck

Debugging CI Failures

# 1. Identify which job is failing
./scripts/manage-ci-jobs.sh list

# 2. Disable other jobs to isolate the issue
./scripts/manage-ci-jobs.sh disable security-ci.yml trufflehog
./scripts/manage-ci-jobs.sh disable security-ci.yml bandit
./scripts/manage-ci-jobs.sh disable security-ci.yml semgrep

# Keep only the failing job enabled
# (gitleaks in this example)

# 3. Push and debug just that job
git push origin main

# 4. Once fixed, re-enable all jobs
./scripts/manage-ci-jobs.sh enable security-ci.yml trufflehog
./scripts/manage-ci-jobs.sh enable security-ci.yml bandit
./scripts/manage-ci-jobs.sh enable security-ci.yml semgrep

Ready to Use Management Scripts?

Get full control over your Guardrails-AI configuration.

View Scripts on GitHub