ci(workflows): migrate ci.yml to dorny/paths-filter detect job (#413)

[yoshi280]

Closes the docs-PR merge block

Branch protection requires pytest (3.12) + pytest (3.13) on every PR. The current ci.yml uses paths-ignore to skip the workflow on docs-only changes — but that makes those checks register as expected (i.e., "not satisfied yet, waiting"), which branch protection treats as a blocker. Result: docs-only PRs cannot merge.

Concretely: #426 (README v1.7 row → shipped) hit this today.

The TODO at the old ci.yml:9-11 calls out exactly this fix: "once branch protection requires this check, migrate to a dorny/paths-filter detection job so the workflow always runs and reports a status, with downstream jobs gated by if:." This PR does that.

What changes

• Workflow always runs on every PR (no paths-ignore).
• New detect job uses dorny/paths-filter@v3.0.2 (SHA-pinned per repo convention) to classify whether the diff touches Python source / tests / pyproject.toml / uv.lock / the workflow itself.
• pytest matrix gates on if: needs.detect.outputs.python == 'true'. When the diff is docs-only, both pytest (3.12) and pytest (3.13) register as skipped — which branch protection accepts as satisfied. When the diff touches Python, both run as before.

Why this works

Branch protection distinguishes:

• expected (workflow excluded by paths-ignore / never registered) → blocks merge.
• skipped (job registered but if: evaluated false) → satisfies the required check.

The migration shifts gating from "does the workflow run at all" to "does the work inside the workflow run." Registration is unconditional; the work is conditional.

Refs

• Prior TODO: .github/workflows/ci.yml:9-11 pre-migration.
• Surfacing PR: docs(readme): v1.7 row → shipped (BM25F default-on; others opt-in) per #154 #426 (README v1.7 row update; cannot merge under current ci.yml).
• Original paths-ignore introduction: PR merging / review / CI pipeline too strict #413.

Closes the gap. After this lands, #426 just needs a close+reopen on its existing branch to retrigger CI under the new logic, then it can FF-merge.

Summary by Sourcery

Migrate the CI workflow to always run on pull requests and use a detection job to conditionally run pytest based on changed files.

CI:

• Replace pull_request paths-ignore configuration with an unconditional trigger so required checks are always registered.
• Introduce a detect job using dorny/paths-filter to determine whether Python-related files changed.
• Gate the pytest job on the detect job output so tests are skipped, not absent, for docs-only or non-Python changes.

[coderabbitai]

Warning

Rate limit exceeded

@yoshi280 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 11 minutes and 28 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8d9f174a-a898-4a80-afa2-c80abb8fe30d

📥 Commits

Reviewing files that changed from the base of the PR and between 95e563b and 60387b3.

📒 Files selected for processing (1)

• .github/workflows/ci.yml

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ci/issue-413-paths-filter-migration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

Migrates the CI workflow from using paths-ignore to a dedicated detect job using dorny/paths-filter so the workflow always runs and pytest jobs are conditionally skipped (not absent), unblocking docs-only PRs under branch protection.

Sequence diagram for CI workflow with detect and pytest jobs

sequenceDiagram
  actor Developer
  participant GitHub
  participant CI_workflow
  participant detect_job
  participant pytest_job
  participant paths_filter

  Developer->>GitHub: push commits / open PR
  GitHub->>CI_workflow: trigger pull_request event

  CI_workflow->>detect_job: start detect job
  detect_job->>paths_filter: run filters for python paths
  paths_filter-->>detect_job: set output python true or false
  detect_job-->>CI_workflow: expose output python

  CI_workflow->>pytest_job: evaluate if condition

  alt python output true
    CI_workflow->>pytest_job: run matrix for Python 3.12 and 3.13
    pytest_job-->>CI_workflow: report success or failure
  else python output false
    CI_workflow-->>pytest_job: mark matrix jobs skipped
  end

  CI_workflow-->>GitHub: report pytest checks registered and completed
  GitHub-->>Developer: show required checks success or skipped

Loading

Flow diagram for paths-filter gating pytest jobs

flowchart TD
  A[Changed files in PR] --> B[Run dorny paths-filter with python filter]
  B -->|matches src tests pyproject toml uv lock ci yml| C[Set output python true]
  B -->|no matches| D[Set output python false]

  C --> E[Run pytest matrix for Python 3.12 and 3.13]
  E --> G[pytest jobs pass or fail]

  D --> F[Mark pytest matrix jobs as skipped]
  F --> H[Branch protection treats checks as satisfied]

Loading

File-Level Changes

Change	Details	Files
Replace workflow-level paths-ignore with a detection job that classifies Python-impacting changes using dorny/paths-filter and exposes the result as a job output.	Remove pull_request.paths-ignore configuration that previously excluded docs-only and similar changes from running the CI workflow. Add a new detect job that checks out the repo, runs step-security/harden-runner, and invokes dorny/paths-filter@v3.0.2 with a "python" filter covering src, tests, pyproject.toml, uv.lock, and the CI workflow file. Expose the paths-filter result as a boolean-like python output on the detect job for downstream use.	.github/workflows/ci.yml
Gate the pytest matrix job on the detect job output so that pytest is registered but skipped when only non-Python files change.	Make the pytest job depend on the detect job via needs: detect. Add an if condition on the pytest job that runs it only when needs.detect.outputs.python == 'true', causing the required checks to appear as skipped rather than expected for docs-only changes. Update workflow comments to document the new detection-job pattern, the branch protection behavior, and the rationale referencing issues PR merging / review / CI pipeline too strict #413 and docs(readme): v1.7 row → shipped (BM25F default-on; others opt-in) per #154 #426.	.github/workflows/ci.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[github-actions]

This PR is now behind main. Rebase locally so your commit signatures stay intact:

git fetch origin && git checkout 'ci/issue-413-paths-filter-migration' && git rebase origin/main
# resolve conflicts if any, then
git push --force-with-lease

Auto-rebase was removed because the bot has no signing key; rebasing as the bot strips author signatures and the required_signatures rule on main then blocks the merge. See #341.

[yoshi280]

[claim:review:Toug:2026-05-06T21:09:00Z]

[yoshi280]

[release:review:Toug:2026-05-06T21:10:56Z]

[yoshi280]

Closed during a rebase attempt that hit a real merge conflict on .github/workflows/ci.yml against current main (edge-rerank ship overlap). Branch restored to original SHA 60387b3 and re-opened as #460. GitHub API would not reopen this PR. Sorry for the churn.