GitHub Actions paths-ignore: Stop Required Museum Caption Checks From Staying Pending

Why a green-looking change can have a pending gate

A museum manages exhibit captions, kiosk code and volunteer documentation in one GitHub repository. To save CI time, a maintainer adds paths-ignore to the caption quality workflow so it will not run when only documentation changes. The change sounds harmless until a pull request is blocked because its required status check remains Pending. GitHub documents this behavior for workflows skipped by path or branch filtering and commit-message skip instructions. A skipped workflow has not produced an approved result for the required check. The right design distinguishes the essential merge gate from optional expensive tasks. Optimize the latter without making the protected branch depend on a workflow that GitHub may never start.

List the checks that branch protection actually requires

Before adding filters, open the repository ruleset or branch protection configuration and write down the exact required status check names. Decide which checks must always report on every pull request: for example, permission review, a caption-schema gate and an overall CI decision. Inventory optional work such as full browser screenshots, long transcript tests or media rendering. A branch rule that requires the result of a workflow you intentionally skip creates an operational contradiction. Do not remove checks from protection simply to make a pull request merge. Instead keep a lightweight stable check that runs for every eligible pull request and evaluates whether heavier tasks were legitimately unnecessary.

Understand paths and paths-ignore semantics

For push and pull_request events, GitHub supports paths to include patterns and paths-ignore to exclude patterns. A workflow with paths-ignore skips only when all changed files match the ignored patterns; one changed file outside those patterns can cause a run. The same event cannot declare both paths and paths-ignore. To combine includes and exclusions, GitHub documents negative patterns prefixed with ! inside paths, where the order of patterns matters. Path filtering is not evaluated for tag pushes. These are trigger rules, not shell-level path checks, and they determine whether a workflow run exists at all. Store the intended glob patterns alongside example file paths in code review notes.

Use a required check that actually runs

A practical structure is an unfiltered pull-request workflow containing a small required gate, plus jobs that conditionally execute expensive caption or kiosk tests based on the changed files. The required gate must evaluate the outcomes of applicable checks and report failure when a necessary test failed; it must not claim success merely because a dependent job was skipped. Another option is to maintain a separately required lightweight workflow that always runs, with optional workflows handling nonrequired tasks. Pick one structure the organization can reason about and document exactly how required checks are aggregated. Keep permissions minimal, especially for fork-origin pull requests. Never pass a privileged publishing token into untrusted change analysis.

Compare skipped, blocked and safely gated states

The first illustrated state shows a documentation-only change that matches an ignore rule. The workflow does not start, so the required check provides no success report. The second state shows a protected merge blocked by Pending, even though the text edit itself might be harmless. The third state shows a stable required gate that starts and explicitly determines whether caption-specific tests are applicable. These are illustrative behavior states, not screenshots of a live repository. A skipped optional test is not evidence of success and should be represented as not applicable. The stable gate should still fail if classification logic is missing or an applicable dependency fails.

Test both documentation-only and mixed changes

Build a synthetic test matrix: a docs-only pull request, a caption JSON edit, a kiosk code change, and a mixed docs-plus-caption edit. Confirm which workflows start, which individual jobs run, and which checks report in branch protection for each case. Include a path that uses a nested subdirectory and a rename, because simple examples can miss glob boundaries. Review the three-dot diff behavior GitHub applies to pull requests versus the two-dot comparisons used for ordinary pushes. Record expected check names and statuses before changing the protection rules. Run the tests on a disposable branch; do not experiment by weakening a production rule during a deadline-sensitive exhibition launch.

Know when diff limits affect path decisions

GitHub documents limits on how changed-file lists are generated for path filtering. Large pushes, diff timeouts or very large comparisons can produce unexpected trigger behavior, including a workflow running regardless of filters or a matching file not appearing in the evaluated subset. These limits are an additional reason not to use an expensive workflow-level filter as the sole required evidence gate. Keep the gate independent of whether the diff listing is complete. For high-volume media repositories, consider a deterministic file manifest produced inside an always-running workflow and conservative fallback to testing when classification is uncertain. A false assumption that no relevant files changed can be more damaging than a slower build.

Separate source review from deployment authorization

Even when a stable required check passes, a museum deployment should remain a separate protected action. A caption check can verify that file structure and accessibility rules passed without deciding whether a curatorial change is historically accurate or approved for publication. Protect production environments with designated reviewers and restrict workflow token permissions. A pull request from a volunteer fork should not be able to influence a privileged publish step simply by changing a filename that escapes a glob. Use trusted workflow definitions and inspect third-party actions before they run. The path filter only selects work; it is neither a rights workflow nor a substitute for editorial sign-off.

Document the merge gate as a promise to reviewers

Write a short CI contract: the required check always appears, relevant caption changes must run validation, irrelevant changes are marked not applicable only through a reviewed decision, and failed tests block merge. Re-run the full scenario matrix whenever patterns, repository layout, GitHub Actions events or branch-protection settings change. Monitor pulls stuck in Pending and investigate rather than changing rules silently. The purpose of paths-ignore is to reduce unnecessary runs, not to create invisible holes in required evidence. An effective museum workflow saves runner time while keeping the quality decision readable to volunteers, curators and maintainers who are not GitHub Actions experts.

Related guides

• GitHub Actions GITHUB_PATH: Use a Caption QA Tool in Later Steps Without Trusting Unknown Binaries
• GitHub Actions GITHUB_ACTION_PATH: Run a Composite Caption Checker From the Right Directory
• GitHub Actions Path Filters: Speed Up Museum Site CI Without Stranding Required Checks

How We Research

Our research consulted these named official documents: GitHub Docs: Workflow syntax and path filters; GitHub Docs: Triggering a workflow; GitHub Docs: Skipping workflow runs. We checked tool behavior, version-specific options, and stated limitations against an illustrative museum scenario. The examples are suggested implementation and editorial review procedures, not production tests. We did not call the services with live patron records, benchmark latency or accuracy, measure storage savings, or obtain third-party consent. All images are original explanatory drawings rather than screenshots or claimed measured results. Verify provider documentation, service availability, access policies and current organization rules before adoption; keep final publication approval with authorized staff.

Frequently Asked Questions