Repository files navigation

A powerfulGitHub Action that enables conditional execution of workflow steps and jobs based on the files modified by pull requests, feature branches, or recent commits.

⚡ Why Use This Action?

• Save Time & Resources: Run slow tasks like integration tests or deployments only for changed components
• Perfect for Monorepos: Ideal for multi-package repositories where you only want to build/test affected packages
• Flexible Detection: Works with pull requests, feature branches, and long-lived branches
• Rich Output Formats: Get file lists in JSON, CSV, shell, or escaped formats
• Advanced Filtering: Support for glob patterns, change types (added/modified/deleted), and predicate quantifiers

-uses:santosr2/conditional-paths-action@v1id:changeswith:filters:|      src:        - 'src/**'      docs:        - 'docs/**'        - '*.md'# Run only if source code changed-name:Build and Testif:steps.changes.outputs.src == 'true'run:npm run build && npm test# Run only if documentation changed-name:Deploy Docsif:steps.changes.outputs.docs == 'true'run:npm run deploy:docs

This action supportsdual Node.js compatibility to maximize compatibility across different environments:

All workflows (CI, security scans, documentation generation, performance benchmarks, and SBOM generation) are validated on a Node.js 22/24 compatibility matrix. This ensures the action works reliably across both development and runtime environments.

Our CI pipeline runs comprehensive testing across:

• Node.js 22: Development, CI, and Dependabot compatibility
• Node.js 24: GitHub Actions runtime validation
• Matrix Strategy:fail-fast: false ensures both versions are fully tested

strategy:fail-fast:falsematrix:node-version:[22, 24]# Full compatibility matrix

This approach provides maximum compatibility while leveraging the latest GitHub Actions runtime capabilities.

For each filter named{filter-name}, the action provides:

This action requires specific permissions depending on the workflow trigger:

permissions:pull-requests:read# Required for pull_request eventscontents:read# Required for repository access

Note: Forpull_request workflows, onlypull-requests: read is required as the action uses the GitHub API for faster performance.

name:Conditional Workflowon:[push, pull_request]jobs:detect-changes:runs-on:ubuntu-latestpermissions:pull-requests:readsteps:      -uses:santosr2/conditional-paths-action@v1id:changeswith:filters:|            src: 'src/**'            docs: 'docs/**'      -name:Build if source changedif:steps.changes.outputs.src == 'true'run:npm run build      -name:Deploy docs if changedif:steps.changes.outputs.docs == 'true'run:npm run deploy-docs

name:Monorepo CIon:[push, pull_request]jobs:changes:runs-on:ubuntu-latestpermissions:pull-requests:readcontents:readoutputs:packages:${{ steps.filter.outputs.changes }}frontend:${{ steps.filter.outputs.frontend }}backend:${{ steps.filter.outputs.backend }}steps:      -uses:santosr2/conditional-paths-action@v1id:filterwith:filters:|            frontend: 'packages/frontend/**'            backend: 'packages/backend/**'            shared: 'packages/shared/**'test-packages:needs:changesif:${{ needs.changes.outputs.packages != '[]' }}strategy:matrix:package:${{ fromJSON(needs.changes.outputs.packages) }}runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4      -name:Test ${{ matrix.package }}run:npm test --workspace=${{ matrix.package }}deploy-frontend:needs:changesif:needs.changes.outputs.frontend == 'true'runs-on:ubuntu-latestenvironment:productionsteps:      -uses:actions/checkout@v4      -name:Deploy Frontendrun:npm run deploy:frontend

# Install actbrew install act# macOS# or curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash# Build the action firstpnpm run package# Test basic scenariosact workflow_dispatch -W .github/workflows/examples/test-action-locally.yml# Test specific jobsact workflow_dispatch -W .github/workflows/examples/test-action-locally.yml -j test-basic-filters# Test with verbose output for debuggingact workflow_dispatch -W .github/workflows/examples/test-action-locally.yml --verbose# Use specific runner image for Node.js compatibilityact -P ubuntu-latest=catthehacker/ubuntu:act-22.04

Complete documentation is available in our organized documentation structure:

• 📖 API Reference - Complete TypeScript API documentation generated with TypeDoc
• 📁 Examples Collection - Real-world usage patterns, test cases, and local testing examples
• 🚀 Local Development - Setup guide for contributors and local development
• 🔄 Migration Guide - Upgrading from previous versions and breaking changes

Our documentation covers all aspects of using and contributing to this action:

• Complete filter syntax and pattern matching
• Advanced configuration options and use cases
• Performance optimization tips and benchmarks
• Security best practices and compliance
• Local testing with act and troubleshooting guides

Performance metrics and benchmarks are continuously monitored and available at/performance:

• Bundle Size: 672KB optimized for GitHub Actions runtime
• Cold Start: ~117K operations/sec for rapid sequential operations
• Filter Processing: 46K+ operations/sec for complex pattern matching
• Memory Usage: <50MB peak for typical monorepo workloads
• Large Scale: Handles 10K+ files efficiently in monorepo environments

Performance is automatically tracked through:

• Automated Benchmarks: Run on every commit and release
• Bundle Analysis: Size tracking with historical trends
• Memory Profiling: Peak usage monitoring across different scenarios
• Real-world Testing: Matrix testing across Node.js 22/24 environments

This repository maintains the highest security standards with comprehensive automated scanning and transparent reporting:

• CodeQL Analysis - Automated SAST vulnerability detection
• Secret Scanning - GitLeaks integration prevents credential leaks
• Dependency Scanning - Trivy scanner monitors for known CVEs
• License Compliance - Validates all dependencies against approved licenses
• SBOM Generation - Complete software supply chain transparency
• Container Security - SHA-pinned actions with minimal permissions

Please report security issues through ourSecurity Policy. Do not create public issues for security vulnerabilities.

• 🛡️ Security Advisories - Published vulnerability reports
• 📊 Security Dashboard - Real-time security status
• 🔗 Dependency Graph - Supply chain visibility

We provide completesupply chain transparency through automatically generated SBOMs in industry-standard format:

A Software Bill of Materials (SBOM) is a comprehensive inventory of all components, libraries, and dependencies used in this action. It provides:

• 🔍 Supply Chain Transparency - Know exactly what's running in your workflows
• ⚖️ License Compliance - Verify all dependencies meet your organization's requirements
• 🛡️ Security Auditing - Track and respond to vulnerabilities in dependencies
• 📋 Regulatory Compliance - Meet emerging software supply chain requirements

• 🌐 Interactive SBOM Viewer - Web interface for browsing components
• 📁 Download SBOM - Machine-readable CycloneDX v1.4 format
• ✅ Verify Integrity - All SBOMs are cryptographically validated

We use the industry-standardCycloneDX v1.4 format, compatible with:

• SPDX tools and validators
• Dependency-Track and other SBOM analysis platforms
• Government and enterprise compliance frameworks
• Open-source supply chain security tools

The SBOM is automatically generated during our build process and updated with every release, ensuring complete accuracy and freshness.

Join our vibrant community for support, feature requests, and collaboration:

Our Discussions are organized into focused categories:

Track development progress and roadmap through our automated project board:

• 🔄 Automated Workflow: Issues and PRs are automatically added and moved through columns
• 📊 Progress Tracking: Clear visibility into what's being worked on and what's coming next
• 🎯 Roadmap Visibility: See planned features and improvements
• 🤝 Contributor Coordination: Understand where help is needed most

The board automatically syncs with:

• New issues → Added to "Todo" column
• In-progress PRs → Moved to "In Progress" column
• Merged PRs → Moved to "Done" column
• Released features → Archived

We welcome contributions from developers of all skill levels! Please see our comprehensiveCONTRIBUTING.md for guidelines.

This project usesmise for consistent toolchain management across development and CI environments:

# Clone the repositorygit clone https://github.com/santosr2/conditional-paths-action.gitcd conditional-paths-action# Install development toolchain (Node.js 22, pnpm 10)mise install# Install dependencies and setup pre-commit hookspnpm install# Run the complete validation pipelinepnpm run ci

Test your changes locally before submitting:

# Build and package the actionpnpm run package# Run comprehensive test suitepnpm run test:coverage# ≥80% coverage required# Test with act (local GitHub Actions runner)act workflow_dispatch -W .github/workflows/examples/test-action-locally.yml# Run performance benchmarkspnpm run bench

• Node.js 22: Required for local development (managed by mise)
• Compatibility Testing: All changes tested against Node.js 22/24 matrix
• Code Quality: ESLint, Prettier, TypeScript strict mode
• Security: Pre-commit hooks enforce security and license compliance
• Documentation: TSDoc required for all public APIs

Thanks to all the amazing people who have contributed to this project! 🙌

See our completeContributors Hall of Fame for detailed recognition and contribution statistics.

This project is licensed under theMIT License - see the file for details.