aerendir/bin-github-actions-matrix

Updates the matrix of required status checks in branch protection rules of a repository hosted on GitHub.

1.1.0 2025-12-18 18:49 UTC

Requires

• php: ^8.3
• knplabs/github-api: ^3.0
• nyholm/psr7: ^1.8
• symfony/console: ^7.4 || ^8.0
• symfony/finder: ^7.4 || ^8.0
• symfony/http-client: ^7.4 || ^8.0
• symfony/yaml: ^7.4 || ^8.0
• thecodingmachine/safe: ^2.0

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.4
• phpstan/phpstan: 2.1.33
• phpstan/phpstan-phpunit: 2.0.10
• rector/rector: 2.2.14
• roave/security-advisories: dev-master
• serendipity_hq/rector-config: 1.1.14
• thecodingmachine/phpstan-safe-rule: 1.4.3

MIT

• Aerendir

• github
• Github Actions
• protection rules
• branch protection
• branch protection rules

README

GitHub Actions Matrix

A CLI tool to sync configured workflows with branch protection rules.

Supports:

Tested with:

Current Status

Do you like this library?
LEAVE A ★

or run
composer global require symfony/thanks && composer thanks
to say thank you to all libraries you use in your current project, this included!

Install Serendipity HQ Bin GitHub Actions Matrix

$ composer require aerendir/bin-github-actions-matrix

This library follows the http://semver.org/ versioning conventions.

Usage

This tool provides two commands to manage GitHub branch protection rules for your repository's workflows.

Available Commands

compare - Compare workflows with protection rules

Compare the workflows configured in your repository with the current matrix of protection rules on GitHub.

vendor/bin/github-actions-matrix compare [options]

Options:

• -u, --username=USERNAME - Your GitHub username
• -b, --branch=BRANCH - The branch to compare
• -t, --token=TOKEN - Your GitHub access token

Example:

vendor/bin/github-actions-matrix compare --username=myuser --branch=main

This command will display a comparison table showing:

• Local workflows and their job matrices
• Current protection rules on GitHub
• Actions needed (sync, remove, or nothing)

sync - Sync workflows with protection rules

Synchronize workflows configured in the repository with the current matrix of protection rules on GitHub.

vendor/bin/github-actions-matrix sync [options]

Options:

• -u, --username=USERNAME - Your GitHub username
• -b, --branch=BRANCH - The branch to sync
• -t, --token=TOKEN - Your GitHub access token

Example:

vendor/bin/github-actions-matrix sync --username=myuser --branch=main

This command will:

1. Remove obsolete protection rules
2. Add new protection rules based on your workflow matrices

Configuration File

To avoid repeatedly providing the same options, you can create a configuration file gh-actions-matrix.php in your project root.

Setup

1. Copy the example configuration file:

   cp gh-actions-matrix.dist.php gh-actions-matrix.php

2. Edit gh-actions-matrix.php to set your default values:

   <?php
   
   $config = new Aerendir\Bin\GitHubActionsMatrix\Config\GHMatrixConfig();
   
   // Set the default GitHub username for the repository
   $config->setUser('your-github-username');
   
   // Set the default branch to sync/compare
   $config->setBranch('main');
   
   return $config;

3. Add gh-actions-matrix.php to your .gitignore file to keep local configurations private.

Priority Order

The commands use the following priority order to determine values:

1. CLI options (highest priority) - --username, --branch
2. Configuration file - values from gh-actions-matrix.php
3. Git configuration - for username only, read from git config
4. Auto-selection - for branch only, if there's only one protected branch
5. Interactive prompt (lowest priority) - asks for missing values

Benefits

• No repeated prompts: Once configured, commands won't ask for user/branch
• Flexible: Command-line options still override config file values
• Project-specific: Each project can have its own configuration
• Secure: Keep sensitive config out of version control

Optional Combinations

Sometimes you want to test your code with a new version of PHP or a dependency to know if it's already compatible, but you don't want the entire workflow to fail if the tests don't pass. This is where "optional combinations" come in.

An optional combination is a matrix combination that is not marked as required in your branch protection rules. This means:

• The job will still run in your GitHub Actions workflow
• If it fails, it won't block merging or mark the overall workflow as failed
• It appears as an optional check in pull requests

Configuring Optional Combinations

Use the markOptionalCombination() method in your gh-actions-matrix.php configuration file:

<?php

$config = new Aerendir\Bin\GitHubActionsMatrix\Config\GHMatrixConfig();

// Set your default configuration
$config->setUser('your-github-username');
$config->setBranch('main');

// Mark specific combinations as optional (not required)
// First argument: workflow name (as defined in your workflow file)
// Second argument: combination to mark as optional

// Example 1: Test PHP 8.4 without making it required
$config->markOptionalCombination('phpunit', ['php' => '8.4']);

// Example 2: Test a specific combination of PHP and Symfony
$config->markOptionalCombination('phpunit', ['php' => '8.3', 'symfony' => '~8.0']);

// You can mark multiple combinations for the same workflow
$config->markOptionalCombination('integration-tests', ['php' => '8.4', 'database' => 'postgresql']);

return $config;

How It Works

When you specify an optional combination:

1. The combination must exist in your workflow matrix. If it doesn't exist or is explicitly excluded, you'll get an error.
2. The job still runs in your GitHub Actions workflow as normal.
3. It's not added to required status checks when you run the sync command.
4. Pull requests can be merged even if the optional combination fails.

Partial Matching

Optional combinations support partial matching. For example:

// This marks ALL combinations with PHP 8.4 as optional, regardless of other matrix values
$config->markOptionalCombination('phpunit', ['php' => '8.4']);

// If your matrix is:
// matrix:
//   php: ['8.3', '8.4']
//   symfony: ['~6.4', '~7.4']
//
// Then these combinations will be marked as optional:
// - phpunit (8.4, ~6.4)
// - phpunit (8.4, ~7.4)

Use Cases

• Testing new PHP versions before they're officially supported
• Experimental dependency versions (e.g., testing Symfony 8.0 before stable release)
• Optional database engines that you want to test but not require
• Performance tests that might be flaky but provide useful information
• Nightly builds or bleeding-edge combinations

Examples

Without config file:

$ vendor/bin/github-actions-matrix sync
# Prompts for username
# Prompts for token
# Prompts for branch (if multiple protected branches)

With config file:

$ vendor/bin/github-actions-matrix sync
# Only prompts for token (username and branch taken from config)

Overriding config file:

$ vendor/bin/github-actions-matrix sync --username different-user --branch dev
# Uses 'different-user' and 'dev' instead of config values

Do you like this library?
LEAVE A ★

or run
composer global require symfony/thanks && composer thanks
to say thank you to all libraries you use in your current project, this included!