跳到主要内容
版本:2.x

GitHub Actions (Workflows)

In public repos, GitHub Actions allow you to run jobs on every commit and pull request for free. These processes can be automated tests, builds, code inspections ..etc. You can find more information about GitHub Actions here.

In this guide, you will learn how to add pre-defined workflows to your extension.

You can use the CLI to automatically add and update workflows to your code:

$ flarum-cli infra githubActions

Backend​

All you need to do is create a .github/workflows/backend.yml file in your extension, it will reuse a predefined workflow by the core development team which can be found here. You need to specify the configuration as follows:

name: Backend

on: [workflow_dispatch, push, pull_request]

jobs:
run:
uses: flarum/framework/.github/workflows/[email protected]
with:
# Different types of jobs
enable_backend_testing: true
enable_phpstan: false

# Additional parameters
backend_directory: .

These are the currently available jobs:

NameKey描述
Tests (PHPUnit)enable_backend_testingEnables backend unit/integration tests
Static Code Analysisenable_phpstanEnables static code analysis
信息

These jobs run on every commit pushed to the main branch or pull request created.

Additional Parameters​

In addition, the following parameters can be provided:

NameKey描述Format
Directorybackend_directoryBackend code location. Contains a composer.json file.string
PHP Versionsphp_versionsThe PHP versions to run jobs onString JSON Array
PHP Extensionsphp_extensionsThe PHP extensions to installComma seperated
Databasesdb_versionsThe databases to run jobs onString JSON Array
PHP ini valuesphp_ini_valuesThe PHP ini values to useComma seperated
Newest PHPlatest_phpThe PHP version that carries the prefixed runs. Used only if it is one of php_versions; otherwise the newest of php_versions is used.string
Table prefixdb_prefixThe table prefix for the prefixed runs on MySQL, MariaDB and SQLitestring
PostgreSQL prefixdb_prefix_pgsqlThe table prefix for the prefixed PostgreSQL runstring
Parallel jobsmax_parallelThe most test jobs of one run to execute at once. Effectively unlimited by default.number
Shorter draftsreduce_draftsRun a shorter check on draft pull requests (see below). Off by default.boolean
提示

How the test matrix is chosen​

The backend tests don't run every PHP version against every database. Each PHP version in php_versions is paired with one version of every database engine in db_versions, the oldest PHP with the oldest version, through to the newest PHP with the newest. The newest version of each engine also runs with a table prefix, because each database driver applies the prefix in its own code. With the default settings that's 11 jobs:

PHPDatabases
8.3MySQL 5.7, MariaDB 10.3, PostgreSQL 10, SQLite
8.4MySQL 8.4, MariaDB 11.8, PostgreSQL 15
8.5MySQL 9.7, MariaDB 12.3, PostgreSQL 18 and SQLite, all with a table prefix

The matrix is built only from the versions you pass:

  • Every PHP version you list runs at least once.
  • If you list only one version of a database engine, it runs both without and with a prefix.
  • Any MySQL, MariaDB, PostgreSQL or SQLite image tag works, for example mysql:8.0 or postgres:16.

For example, this tests PHP 8.4 and 8.5 against MySQL 8.4 and SQLite only:

with:
enable_backend_testing: true
backend_directory: .
php_versions: '["8.4", "8.5"]'
db_versions: '["mysql:8.4", "sqlite:3"]'

Shorter checks for draft pull requests​

With reduce_drafts: true, a draft pull request only runs the newest PHP against the newest version of each database engine, with a table prefix: 4 jobs with the default settings. The full matrix runs once the pull request is marked ready for review, so add ready_for_review to your pull_request trigger types. Pushes to a branch that has an open draft pull request in the same repository count as drafts too.

name: Backend

on:
workflow_dispatch:
push:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]

jobs:
run:
uses: flarum/framework/.github/workflows/[email protected]
with:
enable_backend_testing: true
backend_directory: .
reduce_drafts: true
# Optional: stop one run from taking every runner your account has.
max_parallel: 6

Frontend​

All you need to do is create a .github/workflows/frontend.yml file in your extension, it will reuse a predefined workflow by the core development team which can be found here. You need to specify the configuration as follows:

name: Frontend

on: [workflow_dispatch, push, pull_request]

jobs:
run:
uses: flarum/framework/.github/workflows/[email protected]
with:
enable_bundlewatch: false
enable_prettier: true
enable_typescript: false

frontend_directory: ./js
backend_directory: .
js_package_manager: yarn # npm, yarn or pnpm
main_git_branch: main

secrets:
bundlewatch_github_token: ${{ secrets.BUNDLEWATCH_GITHUB_TOKEN }}
Using pnpm?

If you set js_package_manager to pnpm, you must declare the packageManager field in your extension's js/package.json, for example:

{
"packageManager": "[email protected]+sha512.9a6f330a95b66446ea088faf1521405a8a01f07fde7124cc9958dfed52d4bb436737e65b08f85f37b46fcba375092558ac51262b816844b22f63406ed166bfee"
}

The workflow relies on Corepack to provision pnpm, which reads this field to determine the expected package manager and version. Without it, the workflow will fail.

Running frontend tests

The example above does not run frontend tests. To run them on every push and pull request, add enable_tests: true to the with: block. The workflow runs composer install before the frontend job, so Flarum core is present at vendor/flarum/core/js for the tests to resolve against — no extra configuration is needed. By default it runs your test script; override that with test_script if you use a different script name.

Unlike the backend workflow, the frontend workflow runs everything in a single job. Here are the available parameters: Here are the available parameters:

NameKey描述Format
Build Scriptbuild_scriptScript to run for production build. Empty value to disable. Empty value to disable.string
Build Typings Scriptbuild_typings_scriptScript to run for typings build. Empty value to disable. Empty value to disable.string
Format Scriptformat_scriptScript to run for code formatting. Empty value to disable. Empty value to disable.string
Check Typings Scriptcheck_typings_scriptScript to run for tyiping check. Empty value to disable. Empty value to disable.string
Type Coverage Scripttype_coverage_scriptScript to run for type coverage. Empty value to disable. Empty value to disable.string
Test Scripttest_scriptScript to run for tests. Empty value to disable. Empty value to disable.string
Enable Bundlewatchenable_bundlewatchEnable Bundlewatch?string
Enable Prettierenable_prettierEnable Prettier?string
Enable Typescriptenable_typescriptEnable TypeScript?string
Enable Testsenable_testsEnable Tests?string
Backend Directorybackend_directoryThe directory of the project where backend code is located. This should contain a composer.json file, and is generally the root directory of the repo.string
Frontend Directoryfrontend_directoryThe directory of the project where frontend code is located. This should contain a package.json file.string
Main Git Branchmain_git_branchThe main git branch to use for the workflow.string
Node Versionnode_versionThe node version to use for the workflow.string
JS Package Managerjs_package_managerThe package manager to use. One of npm, yarn or pnpm.string
Cache Dependency Pathcache_dependency_pathThe path to the cache dependency file.string
:::tip

For more details on parameters, checkout the full predefined reusable workflow file.

:::