Frb CI Filter

Use this skill when CI feedback is too expensive and the current task needs a focused GitHub Actions signal instead of automatic full CI.

The preferred mechanism is the formal workflow_dispatch input in .github/workflows/ci.yaml:

gh workflow run ci.yaml --ref <branch> -f 'ci_filter=<filter>'

Do not temporarily hack workflow jobs just to get partial CI unless the formal filter cannot express the target.

1 Filter Syntax

full
job_id
job_a,job_b
job_id[dimension=value]
job_id[dimension=value|other_value,other_dimension=value]
job_a,job_b[dimension=value]

• full or * runs the normal full CI plan.
• job_id runs the whole job, including its full matrix if it has one.
• job_id[...] runs only matching matrix entries.
• Bracket filters currently require dimension=value.
• Commas outside brackets combine multiple jobs.
• Explicit dimension=value conditions inside brackets are ANDed.
• | means OR within one dimension.
• Matrix dimensions include direct keys such as image, package, device, api-level, sanitizer, platforms, and nested matrix.info keys such as platform, target, version.
• Numeric matrix values are matched as strings, e.g. api-level=35.
• Values may contain spaces, e.g. iOS simulator device names.
• Unknown jobs, unknown dimensions, malformed filters, and filters matching no matrix entries fail in the Plan :: CI job.

2 Manual Dispatch Label

Use the ci-manual-dispatch PR label when an agent or human wants to prevent automatic PR CI from running the full surface while iterating.

gh pr edit <pr-number> --add-label ci-manual-dispatch

With the label present:

• normal PR-triggered CI produces an empty plan for the heavy jobs
• workflow_dispatch remains available for explicit focused runs
• the PR must not be treated as merge-ready from partial runs alone

Before final readiness:

gh pr edit <pr-number> --remove-label ci-manual-dispatch

Then let the normal full CI surface run. Removing the label triggers PR CI because the workflow listens to labeled and unlabeled pull request events.

3 Manual Dispatch PR Comment

Manual workflow_dispatch runs of .github/workflows/ci.yaml comment from Plan :: CI on the matching open PR with the selected ci_filter and run link; normal push and pull_request runs do not comment.

4 Local Planning

Before dispatching an expensive manual run, smoke the filter locally:

./frb_internal plan-ci --filter 'test_dart_web[package=frb_example--pure_dart_pde]'

The command emits a GitHub Actions output line:

plan={...}

The workflow consumes it with paths like:

fromJSON(needs.plan_ci.outputs.plan).test_dart_web.enable
fromJSON(needs.plan_ci.outputs.plan).test_dart_web.matrix

That output shape is intentional; each CI job has its own top-level entry containing enable, and matrix jobs also contain matrix.

5 Repeated Precise Validation

Use repeated precise validation when a flaky fix needs several independent executions of one CI job or matrix entry on exactly the same commit.

• Fix the commit: Push the branch once, record its SHA, and do not move the branch until all runs finish.
• Smoke the filter: Run ./frb_internal plan-ci --filter '<filter>' before dispatching.
• Dispatch independently: Create five separate workflow_dispatch runs, not one run with five matrix copies and not five attempts of one run.
• Keep the filter identical: Pass the same exact ci_filter to every dispatch.
• Verify the SHA: Confirm every selected run reports the recorded headSha; a branch name alone is not evidence that queued runs used the same commit.
• Count target jobs: Count the conclusion of the selected job or matrix entry, not the workflow conclusion or skipped jobs.
• Preserve every run link: Report all five run URLs, the fixed SHA, the filter, and the target-job result.
• Do not move or cancel: A new commit invalidates the comparison; cancellation does not count as a completed validation.