{"id":13618035,"url":"https://github.com/laminas/laminas-ci-matrix-action","last_synced_at":"2025-04-14T10:30:58.938Z","repository":{"id":40324866,"uuid":"336072567","full_name":"laminas/laminas-ci-matrix-action","owner":"laminas","description":"GitHub Action for creating a CI job matrix.","archived":false,"fork":false,"pushed_at":"2024-09-18T04:40:34.000Z","size":1574,"stargazers_count":24,"open_issues_count":38,"forks_count":15,"subscribers_count":16,"default_branch":"1.28.x","last_synced_at":"2024-09-18T07:31:32.388Z","etag":null,"topics":["continuous-integration"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laminas.png","metadata":{"funding":{"community_bridge":"laminas-project"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-04T20:20:33.000Z","updated_at":"2024-09-10T21:11:20.000Z","dependencies_parsed_at":"2023-02-18T20:45:56.832Z","dependency_job_id":"8be63f34-ed78-4ecd-86f4-5ade8e1e335b","html_url":"https://github.com/laminas/laminas-ci-matrix-action","commit_stats":{"total_commits":295,"total_committers":10,"mean_commits":29.5,"dds":"0.41694915254237286","last_synced_commit":"683a3e617ab14a51aeb86db71f66cbfec98b2a51"},"previous_names":[],"tags_count":99,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laminas%2Flaminas-ci-matrix-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laminas%2Flaminas-ci-matrix-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laminas%2Flaminas-ci-matrix-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laminas%2Flaminas-ci-matrix-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laminas","download_url":"https://codeload.github.com/laminas/laminas-ci-matrix-action/tar.gz/refs/heads/1.28.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223627301,"owners_count":17175676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["continuous-integration"],"created_at":"2024-08-01T20:01:53.071Z","updated_at":"2025-04-14T10:30:58.929Z","avatar_url":"https://github.com/laminas.png","language":"TypeScript","funding_links":["https://funding.communitybridge.org/projects/laminas-project"],"categories":["TypeScript"],"sub_categories":[],"readme":"# Create a CI matrix for use in a GitHub Action\n\n\u003e ## 🇷🇺 Русским гражданам\n\u003e \n\u003e Мы, участники Laminas, родились и живем в разных странах. У многих из нас есть друзья, родственники и коллеги как в России, так и в Украине. Некоторые из нас родились в России. Некоторые из нас живут в России. У некоторых бабушки и дедушки сражались с фашистами во Второй мировой войне. Здесь никто не поддерживает фашизм.\n\u003e \n\u003e У одного из нас есть украинская родственница, которая спаслась из дома вместе с сыном. Поезд задержался из-за бомбежки на дороге впереди. У нас есть друзья, которые прячутся в бомбоубежищах. Мы с тревогой ждем весточки от них после воздушных налетов, которые беспорядочно наносят удары и попадают по больницам, школам, детским садам и домам. Мы не берем это из каких-либо СМИ. Мы наблюдаем это напрямую.\n\u003e \n\u003e Вы доверяете нам достаточно, чтоб использовать наши программы, и мы просим вас довериться нам вновь. Мы нуждаемся в помощи. Выходите и протестуйте против этой бесполезной войны. Остановите кровопролитие. Скажите \"Нет войне!\"\n\u003e \n\u003e ## 🇺🇸 To Citizens of Russia\n\u003e \n\u003e We at Laminas come from all over the world. Many of us have friends, family and colleagues in both Russia and Ukraine. Some of us were born in Russia. Some of us currently live in Russia. Some have grandparents who fought Nazis in World War II. Nobody here supports fascism.\n\u003e \n\u003e One team member has a Ukrainian relative who fled her home with her son. The train was delayed due to bombing on the road ahead. We have friends who are hiding in bomb shelters. We anxiously follow up on them after the air raids, which indiscriminately fire at hospitals, schools, kindergartens and houses. We're not taking this from any media. These are our actual experiences.\n\u003e \n\u003e You trust us enough to use our software. We ask that you trust us to say the truth on this. We need your help. Go out and protest this unnecessary war. Stop the bloodshed. Say \"stop the war!\"\n\nThis repository represents a GitHub action that allows you to introspect a PHP project in order to build up a test matrix which can later be run by the [laminas/laminas-continuous-integration-action](https://github.com/laminas/laminas-continuous-integration-action).\n\nIt identifies jobs to run based on presence or absence of configuration files in the package.\nCurrently, it identifies the following:\n\n- PHP versions to run unit tests against based on the `php` constraint in the `composer.json` file.\n- Whether to run against a \"locked\" set of dependencies based on the presence of a `composer.lock` file.\n- PHPUnit tests based on the presence of `phpunit.xml.dist` or `phpunit.xml` files.\n- phpcs checks based on the presence of `phpcs.xml.dist` or `phpcs.xml` files.\n- Psalm checks based on the presence of `psalm.xml.dist` or `psalm.xml` files.\n- PHPStan checks based on the presence of `phpstan.neon`, `phpstan.neon.dist` or `phpstan.dist.neon` files.\n- ComposerRequireChecker checks based on the presence of `composer-require-checker.json` file.\n- phpbench benchmarks based on the presence of a `phpbench.json`.\n- Infection mutation tests based on the presence of `infection.json` or `infection.json.dist`. In case that `roave/infection-static-analysis-plugin` is installed, this will be used instead.\n- Markdown documentation based on the presence of a `mkdocs.yml` and/or markdown files in the `doc/book/` or `doc/books/` trees.\n- Codeception checks based on the presence of `codeception.yml.dist` or `codeception.yml` files.\n\nFurther, when triggered by a `pull_request` event, it determines what checks are necessary based on which files were affected.\n\n## Usage\n\n```yaml\njobs:\n  matrix:\n    name: Generate job matrix\n    runs-on: ubuntu-latest\n    outputs:\n      matrix: ${{ steps.matrix.outputs.matrix }}\n    steps:\n      - name: Gather CI configuration\n        id: matrix\n        uses: laminas/laminas-ci-matrix-action@v1\n\n  qa:\n    name: QA Checks\n    needs: [matrix]\n    runs-on: ${{ matrix.operatingSystem }}\n    strategy:\n      fail-fast: false\n      matrix: ${{ fromJSON(needs.matrix.outputs.matrix) }}\n    steps:\n      - name: ${{ matrix.name }}\n        uses: laminas/laminas-continuous-integration-action@v1\n        with:\n          job: ${{ matrix.job }}\n```\n\nGenerally, you will use this as a dependency of a job that uses [laminas/laminas-continuous-integration-action](https://github.com/laminas/laminas-continuous-integration-action), as demonstrated in the above configuration.\n\n\u003e ### actions/checkout not required\n\u003e\n\u003e An actions/checkout step prior to this action is not required, as it will perform a checkout into the WORKDIR on its own if none has been performed previously.\n\u003e We recommend using actions/checkout only if you need to access QA artifacts in a later step.\n\n## Outputs\n\nIt spits out a single output, \"matrix\", which is a JSON string in the following format:\n\n```json\n{\n  \"include\": [\n    {\n      \"name\": \"(string) Name of the check being run\",\n      \"operatingSystem\": \"(string) Name of the OS the job should be run on (generally ubuntu-latest)\",\n      \"action\": \"(string) GHA to run the step on; currently ignored, as GHA does not support dynamic action selection\",\n      \"job\": \"(string) JSON object detailing the job (more on this later)\"\n    }\n  ],\n  \"exclude\": [\n    {\n    }\n  ]\n}\n```\n\nThe \"exclude\" element will only be present if the package using the action provides it via configuration.\nEach item in the \"exclude\" array will be an object, with one or more of the keys listed in the \"include\" objects; when a job matches all elements specified in the \"exclude\" array, it will be excluded from runs.\n\nThe \"job\" element is a string JSON object detailing the job to run.\nNote: it is **not** an object; it is a JSON string but it MUST have the structure as shown [here](#job-element).\n\n### Job Element\n\nThe \"job\" element will have the following elements, but is not restricted to them:\n\n```json\n{\n  \"php\": \"(optional) string PHP minor version to run against; @lowest and @latest aliases point to the minimum and maximum PHP versions which are supported by the project\",\n  \"extensions\": [\n    \"(optional) extension names to install; names are from the ondrej PHP repository, minus the php{VERSION}- prefix\"\n  ],\n  \"ini\": [\n    \"(optional) php.ini directives, one per element; e.g. 'memory_limit=-1'\"\n  ],\n  \"dependencies\": \"(optional) dependencies to test against; one of lowest, locked, latest. default: locked\",\n  \"command\": \"(required) command to run to perform the check\", \n  \"ignore_platform_reqs_8\": \"(optional; deprecated) boolean; whether to add `--ignore-platform-req=php` to Composer for PHP 8.0. default: true\",\n  \"ignore_php_platform_requirement\": \"(optional) boolean; whether to add `--ignore-platform-req=php` to Composer for this job.\",\n  \"additional_composer_arguments\": [\n      \"(optional) list of arguments to be passed to `composer install` and `composer update`\"\n  ]\n}\n```\n\n## Configuration\n\nThe package can include a configuration file in its root, `.laminas-ci.json`, which can provide the following:\n\n```json\n{\n  \"extensions\": [\n    \"extension names to install\"\n  ],\n  \"ini\": [\n    \"php.ini directives\"\n  ],\n  \"checks\": [\n    {\n    }\n  ],\n  \"additional_checks\": [\n    {\n    }\n  ],\n  \"exclude\": [\n    {\n    }\n  ],\n  \"ignore_php_platform_requirements\": {\n      \"8.0\": true\n  },\n  \"stablePHP\": \"8.0\",\n  \"additional_composer_arguments\": [\n  ]\n}\n```\n\n### Providing specific checks to run\n\nIf you do not want to autodiscover checks to run, you can provide the \"checks\" configuration.\nEach element in that array should be in the same format as listed above for the outputs:\n\n```json\n{\n  \"name\": \"(string) Name of the check being run\",\n  \"operatingSystem\": \"(string) Name of the OS the job should be run on (generally ubuntu-latest)\",\n  \"action\": \"(string) GHA to run the step on; currently ignored, as GHA does not support dynamic action selection\",\n  \"job\": \"(object|string) JSON object detailing the job\"\n}\n```\n\nThe \"job\" element can either be a JSON string representing a job, or an object.\nIn each case, it MUST have the structure as shown [here](#job-element) **but** the \"php\" element is mandatory in here and MUST contain\nthe minor PHP version to run the check against.\n\nThe action validates each check and its job to ensure it is structured correctly, and will provide warnings if not, omitting any check that is malformed from the output.\n\n**If the `checks` element is populated, the matrix will not include any auto-detected checks, and will only output the jobs listed in that element.**\n\n### Providing additional checks\n\nThe `additional_checks` key allows package authors to provide checks to run in addition to any discovered.\nThis allows providing checks for tools the matrix discovery tools do not know about, or providing one-off checks (such as benchmarks or mutation tests).\n\nThe syntax for the `additional_checks` key is as follows:\n\n```json\n{\n    \"additional_checks\": [\n        {\n            \"name\": \"(string; REQUIRED) name of the check to run\",\n            \"job\": \"(object) JSON object detailing the job\"\n        }\n    ]\n}\n```\n\nA job per PHP version per dependency set will be created, and the \"name\" will be appended with \"on PHP {VERSION} with {DEPS} dependencies\" during an actual run.\nThe \"job\" element MUST have the structure as shown [here](#job-element) **but** the \"php\" element is mandatory in here and MUST contain either the minor PHP version to run the check against or a wildcard `*` to run the against **all** supported PHP versions.\nYou can pass the wildcard, \"*\", for the \"php\" element; when you do, the `ignore_php_platform_requirement` element will be ignored. It is possible to provide per-version flags by adding the `ignore_php_platform_requirements` element instead.\n\nThe tool discovers checks first, then appends any `additional_checks` are concatenated, and then any `exclude` rules are applied.\n\n### Excluding specific jobs\n\nYou can exclude specific jobs by using their names:\n\n```json\n{\n  \"exclude\": [\n    {\n      \"name\": \"PHPUnit\"\n    }\n  ]\n}\n```\n\nIf you want to limit the exclusion to specific PHP versions, you can additionally add a PHP version:\n\n```json\n{\n   \"exclude\": [\n      {\n         \"name\": \"PHPUnit\",\n         \"php\": \"8.0\"\n      }\n   ]\n}\n```\n\nIn case you only want to exclude jobs for specific Composer dependency sets, add `dependencies` to the `exclude` configuration:\n\n```json\n{\n   \"exclude\": [\n      {\n         \"name\": \"PHPUnit\",\n         \"php\": \"8.0\",\n         \"dependencies\": \"latest\"\n      }\n   ]\n}\n```\n\n## Testing matrix generation locally using Docker\n\nTo test matrix generation in a local checkout on your own machine, you can do the following:\n\n```bash\n$ docker run -v $(realpath .):/github/workspace -w=/github/workspace ghcr.io/laminas/laminas-ci-matrix:1\n```\n\nThis will run the action locally and detail what matrix will be produced; it can be particularly useful for debugging issues with your `.laminas-ci.json` configuration.\n\n## Development\n\nIn case you want to contribute features, bugfixes, tests or JSONSchema enhancements, you might want to build the docker container locally.\n\nTo do so, you can follow these steps:\n\n1. Build the docker container by executing `$ docker build -t laminas/laminas-ci-matrix-action:dev-local .`\n2. Change to the `tests/` directory you want to create a matrix for\n3. Run the docker container while overriding the `entrypoint.sh` to ensure the `diff` is being passed to the matrix generator\n   - `docker run -it --entrypoint \"/action/main.js\" -v $(realpath .):/github/workspace -w=/github/workspace docker.io/laminas/laminas-ci-matrix-action:dev-local $(test -r diff \u0026\u0026 cat diff || echo \"\")`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaminas%2Flaminas-ci-matrix-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaminas%2Flaminas-ci-matrix-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaminas%2Flaminas-ci-matrix-action/lists"}