Use native path filters on push and pull_request events to trigger a workflow only when relevant files change: on: { push: { paths: ['services/api/**', 'shared/**'] } }
Add paths-ignore at the workflow level to exclude documentation or config files that should not trigger builds: paths-ignore: ['docs/**', '**.md']
For fine-grained per-job filtering inside a single workflow, use the dorny/paths-filter action: it outputs boolean variables per defined path pattern that you can reference in subsequent job conditions via if: needs.changes.outputs.api == 'true'
Always include the workflow file itself in path filters (e.g., .github/workflows/api.yml) so that CI configuration changes are validated without requiring a source code change
Include shared library paths in every service's path filter; if service A depends on shared/utils/, changes there should trigger service A's CI even if no service A files changed
Be aware that paths filters on pull_request do not apply when the PR is added to a merge queue — merge_group events ignore path filters and always run the workflow
Known gotchas
Native paths filters and paths-ignore cannot be used together in the same event trigger for a single workflow — choose one approach; if you need both, restructure into separate workflow files
Required status checks configured in branch protection must always pass; if a path filter prevents a workflow from running, the required check is never reported and the PR is blocked — use dorny/paths-filter with a skip-unchanged output instead of workflow-level path filters for required checks
Paths filters use glob patterns evaluated against changed files relative to the repository root; they do not support negative patterns (use paths-ignore for exclusions)
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp