GitHub/Actions

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

https://github.com/features/actions

Microsoft's GitHub Actions is a powerful automation platform that is built-in to, and integrated with GitHub. With a Yaml-based syntax, it is similar to IBM's (RedHat) Ansible automation platform or others like Microsoft's Azure DevOps Pipelines, Amazon AWS CodePipeline, Jenkins, CircleCI, GitLabCI etc... It allow you to automate build, test, and deployment processes within your code repository; defining workflows using YAML files and utilizing different runner environments to execute tasks.

While GitHub's hosted runners only include 'windows-latest', 'macos-latest' and Ubuntu Linux^[1], you can use a Docker Image inside Ubuntu to evaluate your action on a different flavor of Linux like Debian^[2].

From Zero to Hero in 90 Minutes[edit]

Davide "CoderDave" Benvegnu can take you from zero to hero in 90 minutes as he covers most of the fundamentals of GitHub Actions.

Examples[edit]

The Semantic MediaWiki project has a good example of using GitHub Actions.

See the main workflow at https://github.com/SemanticMediaWiki/SemanticMediaWiki/blob/master/.github/workflows/main.yml

Professional Wiki has a good example of doing full testing with a scripted approach to installing MediaWiki instead of the docker based approach of Semantic MediaWiki

ProWiki Example of installing MediaWiki[edit]

https://github.com/ProfessionalWiki/ExternalContent/blob/master/.github/workflows/installMediaWiki.sh

Here's a clear walkthrough of what .github/workflows/ci.yml does and why.

High-level[edit]

Triggers: runs on push and pull_request.
There are three independent jobs run (by default in parallel): test, static-analysis, and code-style.
The workflow tests multiple MediaWiki releases and PHP versions (matrix) and runs linters / static analysis on a specific target (REL1_43 / PHP 8.3).

Job: test[edit]

Purpose: install MediaWiki, install the extension, run PHPUnit tests, and optionally collect coverage and parser tests.
Matrix:

 - Runs for these combinations:
   - REL1_39 with PHP 8.1
   - REL1_40 with PHP 8.1
   - REL1_41 with PHP 8.2
   - REL1_42 with PHP 8.2
   - REL1_43 with PHP 8.3
   - master with PHP 8.4 (marked experimental: true)
 - continue-on-error is set to matrix.experimental, so the master run can fail without failing the whole workflow.

Runner: ubuntu-latest
Defaults: run steps in working-directory mediawiki (so many commands run relative to mediawiki).
Key steps (in order):

 1. Setup PHP with shivammathur/setup-php using the matrix PHP version; enable mbstring and intl extensions and composer tool.
 2. Cache MediaWiki directory using actions/cache, with key mw_$Template:Matrix.mw-php$Template:Matrix.php; the path caches the mediawiki checkout but explicitly excludes mediawiki/extensions/ and mediawiki/vendor/ so the extension and vendor are handled separately.
 3. Cache Composer cache (~/.composer/cache) keyed by composer-php$Template:Matrix.php.
 4. Checkout the repo into a path called EarlyCopy (actions/checkout with path: EarlyCopy). That copy is used to run the provided install script.
 5. Install MediaWiki (only if cache missed) by running EarlyCopy/.github/workflows/installMediaWiki.sh with args: $Template:Matrix.mw ExternalContent. This step runs from the home directory.
 6. Checkout the extension into mediawiki/extensions/ExternalContent (another actions/checkout with that path).
 7. Run composer config --no-plugins allow-plugins.composer/installers true to allow composer/installers plugin (avoids composer blocking plugin execution).
 8. Run composer update (updates/installs dependencies — note: update modifies the lock file if present).
 9. Run php maintenance/update.php --quick to update DB schema.
 10. Run PHPUnit: php tests/phpunit/phpunit.php -c extensions/ExternalContent/
 11. If matrix.mw == 'master': run PHPUnit again with --coverage-clover coverage.xml, then upload coverage to codecov (bash <(curl -s https://codecov.io/bash)).
 12. If matrix.mw >= 'REL1_43': run parser tests php tests/parser/parserTests.php with the tests file; intended to run for REL1_43+ builds.

Notes on test job behavior[edit]

The caching setup excludes mediawiki/extensions and vendor so the extension can be checked out into the MediaWiki tree separately and composer/vendor can be recreated for the tested environment.
The master job is marked experimental (experimental: true) and therefore allowed to fail without failing the workflow (continue-on-error).
The conditional steps enable coverage upload and parser tests only for later MediaWiki versions or master.

Job: static-analysis[edit]

Purpose: run static analysis tools (PHPStan and Psalm) and publish results as PR comments/annotations.
Matrix: single include:

 - mw: REL1_43, php: 8.3

Runner: ubuntu-latest
Defaults: working-directory mediawiki/extensions/ExternalContent (so commands run inside extension dir).
Key steps:

 1. Setup PHP (shivammathur/setup-php) with php 8.3, mbstring extension, and tools composer, cs2pr (cs2pr converts checkstyle XML into pull request comments).
 2. Cache MediaWiki with key mw_static_analysis (same pattern excluding extensions/vendor).
 3. Cache Composer cache with key composer_static_analysis.
 4. Checkout EarlyCopy and install MediaWiki if cache missed using the same installMediaWiki.sh script.
 5. Checkout the extension into mediawiki/extensions/ExternalContent.
 6. composer config --no-plugins allow-plugins.composer/installers true
 7. composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader (uses lockfile to install deps reproducibly).
 8. Run PHPStan: php vendor/bin/phpstan analyse --error-format=checkstyle --no-progress | cs2pr
    - PHPStan outputs checkstyle XML which is piped into cs2pr to create PR comments/annotations.
 9. Run Psalm: php vendor/bin/psalm --shepherd --stats
    - shepherd and stats options are used to report results (and integrate with shepherd if configured).

Job: code-style[edit]

Purpose: run PHP CodeSniffer (phpcs) to enforce code style.
Matrix: single include:

 - mw: REL1_43, php: 8.3

Runner: ubuntu-latest
Defaults: working-directory mediawiki/extensions/ExternalContent
Key steps:

 1. Setup PHP with mbstring, intl, and php-ast extension, tools: composer.
 2. Cache MediaWiki and composer cache (same keys as static-analysis).
 3. Checkout EarlyCopy and install MediaWiki if cache missed.
 4. Checkout the extension into mediawiki/extensions/ExternalContent.
 5. composer config --no-plugins allow-plugins.composer/installers true
 6. composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
 7. Run vendor/bin/phpcs -p -s to report code style issues.

General/implementation notes and intent[edit]

The workflow is designed to test the extension against multiple MediaWiki releases and PHP versions, while keeping static analysis and style checks focused on a single target (REL1_43 / PHP 8.3).
Using actions/checkout path= allows having a copy of the repository at EarlyCopy (for the install script) and then placing the extension source under mediawiki/extensions/ExternalContent.
Caching MediaWiki speeds up repeated runs: the installMediaWiki.sh is skipped when mediawiki cache hit is true.
Composer usage: test job runs composer update (useful for CI that may want newest deps for the tested environments), whereas static-analysis and code-style run composer install to reproduce the locked dependency set and faster installs.
Coverage is only collected for master (coverage generation and upload to codecov).
cs2pr is used to transform static analysis checkstyle output into PR comments so developers can see issues in the GitHub UI.