How to Skip CI for Docs-Only Changes

A one-line README edit does not need the full build and test suite. Path filters skip CI for docs-only changes and save the minutes.

Path filtering lets a workflow ignore changes that only touch docs. The subtlety is required status checks: a skipped job can block a merge unless you handle it, so the pattern needs a shim.

1. Ignore docs paths

Use paths-ignore so pushes that only touch docs do not trigger the heavy workflow.

on:
  pull_request:
    paths-ignore:
      - '**/*.md'
      - 'docs/**'

2. Keep required checks green

If CI is a required check, a skipped run leaves the check pending and blocks merge. Add a lightweight job that always passes for the ignored paths.

jobs:
  ci-required:
    runs-on: ubuntu-latest
    steps:
      - run: echo "docs-only change, no build needed"

3. Be careful what counts as docs

A change to a config file or a code comment that affects behavior is not docs. Scope paths-ignore narrowly to genuine documentation so you never skip a real build.

Key takeaways

• paths-ignore skips heavy CI on docs-only changes.
• Add a passing shim job so required checks do not block the merge.
• Scope the ignore list narrowly to avoid skipping real builds.

Related guides