Branch and path filters — narrowing triggers by branch name and changed files

A branch filter says only run for this branch. A path filter says only run when these files changed. Both evaluate before the runner is allocated, so the guard they express is the cheapest you can write.

Branch and path filters

on:
  push:
    branches:
      - main
      - 'releases/**'
    branches-ignore:
      - 'wip/**'
    paths:
      - 'src/**'
      - 'infra/**'
    paths-ignore:
      - 'docs/**'
      - '**.md'

branches: is the allow list; the trigger fires only when the ref matches. branches-ignore: is the deny list. If both are present, both must be satisfied. Pattern grammar is glob: * matches one segment, ** matches many. The GitLab CI equivalent is a rules: clause at the job level.

flowchart TD
    A[Event arrives] --> B{Branch filter passes?}
    B -- "no" --> Z[Skip silently]
    B -- "yes" --> C{Path filter present?}
    C -- "no" --> R[Run - implicit match-all]
    C -- "yes" --> D{Any changed file in paths?}
    D -- "yes" --> R
    D -- "no" --> E{Any changed file in paths-ignore?}
    E -- "yes" --> Z
    E -- "no" --> R

Three rules that catch the common errors:

• No paths: filter means match-all. Empty paths: [] is not the same as no paths: key.
• paths-ignore: only fires when paths: produced no match. A change touching both src/foo (in paths:) and docs/index.md (in paths-ignore:) still triggers.
• Filter by directory, not extension. infra/** outlives **.tf.

Combining them safely

The pattern that avoids the failure mode is one declarative statement of intent:

on:
  push:
    branches: [main]
    paths: ['infra/**']
    paths-ignore: ['infra/experimental/**']
  pull_request:
    branches: [main]
    paths: ['infra/**']

Read aloud: on push or pull request to main, where the diff touches infra but not the experimental subtree. The intersection is the case you actually care about. Path filters evaluate client-side at the API layer before any workflow file is read - the cost is a diff comparison, not a runner allocation. The trade-off is they only see the diff at the commit boundary.

Production discipline

1. Default-deny, not default-allow. An explicit branches: and paths: list says run only for these.
2. Quote patterns. 'releases/**' today; the unquoted form will break when YAML 1.3 lands.
3. Test the empty intersection. Is there a plausible change that satisfies all clauses? If not, the workflow never runs.
4. Do not filter by extension. Filter by directory.

Cross-course references

• Ansible for Production Sysadmins - Part VI covers directory-based inventory patterns.
• Terraform for Production Sysadmins - Part XII covers the layout of infra/ in a repository.

Quiz