2.0.1

bin-github-actions-matrix 2.0.1

A patch release with two fixes that let sync run with minimal-permission tokens and stop it from adding required checks that can never pass on a pull request. No breaking changes; drop-in over 2.0.0.

🐛 Fixed

• sync no longer needs Contents: Read when the branch is already known. Listing the repository branches (GET /branches) requires Contents: Read on fine-grained tokens, whereas reading branch protection only needs Administration: Read. The tool used to list branches unconditionally, so a minimal-permission token failed with a 403 even when the branch had already been provided. Branches are now listed only when they are actually needed — to populate the interactive chooser, i.e. only when no branch is given on the CLI (--branch) or in the config (setBranch()). (#80)
• Actionable errors for branch-access problems. A 403 while listing branches now explains that the token needs Contents: Read (or that you can pass --branch / setBranch() to skip listing altogether); a 404 while reading branch protection now tells you the branch either does not exist or has no protection rules — for every source the branch may come from (CLI, config, interactive chooser). (#80)
• Required-check derivation is scoped to pull-request-eligible workflows. sync used to derive required checks from every workflow, including ones that never run on pull requests (e.g. schedule- or workflow_dispatch-only). Those checks would sit forever as pending "expected" checks and block PRs. Workflows are now considered only when triggered by push, pull_request or pull_request_target; schedule-/dispatch-only workflows are excluded automatically — no manual ignoreJob() needed — and the exclusion is reported as a plain informational line, not a warning. (#82)

Upgrade notes

• Nothing to change: both fixes are backward-compatible.
• If you were granting Contents: Read only so the tool could list branches, you can now drop it and pass --branch (or set setBranch()), keeping the token at Administration: Read.
• Any ignoreJob() entries you added to your config purely to keep the jobs of a schedule/workflow_dispatch-only workflow out of the required set are now redundant — the tool excludes those workflows on its own — and can be removed.
• If a schedule/workflow_dispatch-only workflow was contributing a required check you actually want to keep, declare it explicitly with addRequiredCheck().
• Before 2.0.1 these non-PR workflows were read like any other and had to be excluded by hand; now that the tool skips them on its own, that explicit, manual exclusion is no longer necessary and should be removed from your config — the resulting required-checks set is unchanged.

2.0.0

bin-github-actions-matrix 2.0.0

A major release focused on making the tool dependency-light and container-friendly, plus richer, safer sync behaviour. It supersedes the 1.x line.

⚠️ Breaking changes

• Removed the thecodingmachine/safe dependency. Every Safe function call has been replaced with the native PHP function guarded by explicit fail-fast handling: on failure the tool now throws its own exceptions instead of Safe's. This removes a transitive dependency and silences its Implicitly marking parameter ... as nullable deprecations under PHP 8.4. (#78)
• Removed the standalone compare command. The read-only comparison is now sync --dry-run. Update any script, Composer alias or CI step that still invokes compare.

✨ Added

• sync --check — read-only CI gate that exits 0 (aligned), 1 (drift) or 2 (error), so a pipeline can fail on protection drift without mutating anything. (#65)
• Confirmation before applying changes. sync now prompts before writing branch-protection rules; pass --force / -f to skip it (for automation). (#70)
• Containerized / monorepo support. New --project-dir / setProjectDir() and --workflows-dir / setWorkflowsDir() to declare where the workflows live, --repo / setRepoName() to set the repository name with a git fallback, and token-file resolution that no longer needs git (falls back to the working directory). Together these let the tool run from inside a container that mounts only a sub-project, with neither .git nor the repo-root .github inferable. (#43, #44, #46)
• Token from the environment. The GitHub token can be resolved from the GH_MATRIX_TOKEN environment variable. (#68)
• matrix.include expansion. Entries under matrix.include are expanded into the generated combinations. (#72)
• Jobs without a strategy are handled as a single required check instead of being skipped. (#71)
• Non-statically-derivable check contexts no longer break sync: a job whose real context cannot be computed statically is skipped with a hint to declare it explicitly (see addRequiredCheck() below) instead of being silently miscomputed. (#73, #74)

Fine-grained control over the required set

New configuration methods let you declare exactly which checks sync keeps, adds or leaves alone — so it can safely remove stale matrix contexts without ever deleting a check it cannot read from the workflows. (#67)

• addRequiredCheck(string $checkName) — declare an external / non-workflow required check (e.g. codecov) that lives in no workflow file. It enters the desired set as a bare-name context: sync never removes it and adds it if missing. This is the way to keep a required check that is not produced by any workflow matrix.
• ignoreJob(string $jobId) — exclude a job (by its id in the workflow) from the required set entirely: it is never added and is removed if currently present. Useful for jobs that must run but never gate merges (e.g. a deploy job).
• markOptionalCombination(string $workflowName, array $combination) — mark a single matrix leg as optional (not required), e.g. an allowed-to-fail PHP/dependency combination.

🐛 Fixed

• Workflow discovery ignores nested, non-workflow YAML (e.g. composite-action metadata under .github/workflows/actions/**), which previously made the reader fail on files without a name key. (#77)
• Workflow discovery also matches the .yaml extension, not only .yml. (#59)
• Fine-grained PATs are accepted by the token validator. (#60)
• Consistent prompt error handling and null-safety across the CommandOption classes. (#69)

Upgrade notes

• Replace compare invocations with sync --dry-run.
• Nothing in the public config API was removed; the new setProjectDir(), setWorkflowsDir(), setRepoName(), addRequiredCheck(), ignoreJob() and the GH_MATRIX_TOKEN env var are additive and optional.
• If any required check on your branch does not come from a workflow matrix (e.g. codecov, or a job whose context is not statically derivable), declare it with addRequiredCheck() before running sync, otherwise sync will remove it as unknown.

1.0.1

What's Changed

• Improve logic to get the name of the repo. by @Aerendir in #13
• Support selection of branch to analyse. by @Aerendir in #17

Full Changelog: 0.1.3...1.0.1

First stable version

1.0.0

Merge branch 'hotfix/0.1.2'