CI for Silverstripe modules

Uses feature detection based on files in the root folder such as phpunit.xml.dist to build and run a dynamic matrix of jobs.

It's highly recommended that you use a tagged version (e.g. v1) to ensure stability of your builds. If you have a relatively simple build that you have no intention of ever making more complex e.g. only phpunit tests using phpunit.xml.dist, then this is probably all you need for long term use.

Note: Unlike other silverstripe/gha-* repositories, this one is a reusable workflow rather than an action. A reusable workflow is required to create a matrix.

Create the following file in your module, and substitute the tagged version for the most recent tag prefixed with a v e.g. @v1

.github/workflows/ci.yml

name: CI

on:
  push:
  pull_request:
  workflow_dispatch:

permissions: {}

jobs:
  ci:
    name: CI
    permissions:
      pull-requests: read
      contents: read
      actions: write
    uses: silverstripe/gha-ci/.github/workflows/ci.yml@v1

on:
  # Run once per week
  schedule:
  - cron: '0 0 * * 1'

permissions: {}

jobs:
  ci:
    name: CI
    permissions:
      pull-requests: read
      contents: read
      actions: write
    # Only run the cron on the account hosting this repository, not on the accounts of forks
    # Change '<account_name>' to match the name of the account hosting this repository
    if: (github.event_name == 'schedule' && github.repository_owner == '<account_name>') || (github.event_name != 'schedule')
    uses: silverstripe/gha-ci/.github/workflows/ci.yml@v1

Set config specific to your needs via "inputs" defined under the with: key. For instance, to disable PHP linting because your module does not yet have a phpcs.xml.dist file

jobs:
  ci:
    name: CI
    uses: silverstripe/gha-ci/.github/workflows/ci.yml@v1
    with:
      phplinting: false

Require additional modules through composer for matrix entries. You do not need to quote the string for multiple requirements composer_require_extra: silverstripe/widgets:^2 silverstripe/comments:^3

Use composer install rather than default composer update. A composer.lock file must be present. Intended only for testing branches of silverstripe/installer or silverstripe/recipe-kitchen-sink where multiple pull-requests need to be tested together. If true will cause composer_require_extra input to be ignored. If dynamic_matrix input also is true then jobs will only be created for the PHP version defined in config.platform.php in composer.json (recommended), or the lowest supported PHP version. There will also be no --prefer-lowest jobs created. Default is false, enable with: composer_install: true

Create a smaller matrix with only the lowest supported PHP and MySQL versions instead of a full matrix of multiple PHP and database versions. Default is false, enable with: simple_matrix: true

Dynamically generate a matrix using feature detection. If disabled, jobs must be defined using the extra_jobs input. Default is true, disable with: dynamic_matrix: false

Runs linting against documentation using silverstripe/documentation-lint if the .doclintrc config file is available. Default is true, disable with: doclinting: false

Runs PHPunit if the phpunit.xml or phpunit.xml.dist config file is available. Default is true, disable PHPunit tests with: phpunit: false

Skips specific PHPUnit suites in the dynamically generated matrix. Default is to run all suites. Configure with: phpunit_skip_suites: suite-to-skip,another-to-skip

Runs phpcs and phpstan if the phpcs.xml.dist or phpstan.neon.dist config files are available. Default is true, disable with: phplinting: false

Run codecov, which does not require a configuration file. Default is false, though for CI runs on the silverstripe account this option will be ignored and codecov is set to run in gha-generate-matrix. Enable with: phpcoverage: true

Force codecov off for CI runs on the silverstripe account. Default is false. Enable with: phpcoverage_force_off: true

Runs behat tests if behat.yml is available. Default is true, disable with: endtoend: false

Runs yarn lint, yarn test and yarn build + git diff-files + git diff if the package.json file is available. Default is true, disable JS tests with: js: false

Define specific test combinations (e.g. php and db versions). All inputs are false by default so you only need to include config for the input(s) you want enabled. All inputs except dynamic_matrix, simple_matrix, and phpunit_skip_suites are available in this context. There are also some additional inputs specific to the extra_jobs input (see below). Use a multi-line yml string

extra_jobs: |
  - php: '8.0'
    db: pgsql
    phpunit: true
    phpunit_suite: api
  - php: '8.1'
    endtoend: true
    endtoend_suite: admin
    endtoend_config: vendor/silverstripe/admin/behat.yml

Additional inputs that can be applied to individual jobs within the extra_jobs input

The version of PHP to run e.g. 8.1

The database to run e.g. mysql80

Valid db are:

• pgsql
• mysql57
• mysql80
• sqlite3
• mariadb

Add a specific suffix to job and artifact names to make them easier to identify. This will be trucated if greater than 20 characters. Must match the regex [a-zA-Z0-9_\- ]

The PHPUnit suite to run as defined in phpunit.xml. Translates to the --testsuite parameter passed to phpunit. Specify 'all' to run all PHPunit suites available in the context of this module/recipe

By default, the workflow will want try to delete tests for modules in the vendor folder to avoid potential conflicts with tests rewritten for different PHPUnit versions. This behaviour is not always desirable because you may want to run those tests for your current build.

Setting this input to true will preserve tests in the vendor folder.

The end-to-end suite as defined in behat.yml. Must be defined, specify 'root' to run the default suite

The behat.yml config file to use if not using the root behat.yml. Only used if running behat tests in a different module

Must be true or false. Determines whether to install in-memory cache extensions for framework unit tests.