Skip to content

docs(core): update backend workflow documentation #534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DavideIadeluca wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(core): update backend workflow documentation #534

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8d0f5f7
docs(core): update backend workflow documentation
DavideIadeluca Jun 10, 2026
9c8a435
Update github-actions.md
DavideIadeluca Jun 10, 2026
d4ad7ee
Update update-2_0.md
DavideIadeluca Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 38 additions & 28 deletions docs/extend/github-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ In this guide, you will learn how to add pre-defined workflows to your extension
:::tip [Flarum CLI](https://github.com/flarum/cli)

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

```bash
$ flarum-cli infra githubActions
```
Expand All @@ -15,54 +16,62 @@ $ 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](https://github.com/flarum/framework/blob/main/.github/workflows/REUSABLE_backend.yml). You need to specify the configuration as follows:
Create `.github/workflows/backend.yml` in your extension. It uses a [reusable workflow](https://github.com/flarum/framework/blob/2.x/.github/workflows/REUSABLE_backend.yml) that runs PHPUnit across a matrix of PHP versions, databases, and table prefixes — and optionally PHPStan static analysis.

```yaml
name: Backend
name: ACME Foobar PHP

on: [workflow_dispatch, push, pull_request]

jobs:
run:
uses: flarum/framework/.github/workflows/REUSABLE_backend.yml@main
uses: flarum/framework/.github/workflows/REUSABLE_backend.yml@2.x
with:
# Different types of jobs
enable_backend_testing: true
enable_phpstan: false

# Additional parameters
backend_directory: .
enable_phpstan: true
```

These are the currently available jobs:

| Name | Key | Description |
|-------------------------------------------------|--------------------------|----------------------------------------|
| [Tests (PHPUnit)](testing.md) | `enable_backend_testing` | Enables backend unit/integration tests |
| [Static Code Analysis](static-code-analysis.md) | `enable_phpstan` | Enables static code analysis |

:::info

These jobs run on every commit pushed to the main branch or pull request created.
Runs on every push and on pull requests from forks. Internal pull requests are skipped to avoid duplicate runs triggered by the push event.

:::

### Additional Parameters
### Inputs

**Job controls**

In addition, the following parameters can be provided:
| Input | Description | Default |
| ------------------------ | ----------------------------------------------------------------------------------------------- | ------- |
| `enable_backend_testing` | Run [PHPUnit integration tests](testing.md) | `true` |
| `enable_phpstan` | Run [PHPStan static analysis](static-code-analysis.md) — disabled by default, opt in explicitly | `false` |

| Name | Key | Description | Format |
|----------------|---------------------|---------------------------------------------------------|-------------------|
| Directory | `backend_directory` | Backend code location. Contains a `composer.json` file. | string |
| PHP Versions | `php_versions` | The PHP versions to run jobs on | String JSON Array |
| PHP Extensions | `php_extensions` | The PHP extensions to install | Comma seperated |
| Databases | `db_versions` | The databases to run jobs on | String JSON Array |
| PHP ini values | `php_ini_values` | The PHP ini values to use | Comma seperated |
**Configuration**

These inputs have sensible defaults, which are updated over time as new PHP and database versions are released. The most common reason to override them is to narrow the matrix to your extension's supported PHP or database versions.

| Input | Description | Default |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `php_versions` | PHP versions to test (JSON array). Should match your extension's declared PHP support range. | `'["8.3", "8.4", "8.5"]'` |
| `db_versions` | Database images to test (JSON array). Supports `mysql`, `mariadb`, `postgres`, and `sqlite`. | `'["mysql:9.7", "mariadb:12.3", "postgres:18", "sqlite:3"]'` |
| `db_prefixes` | Table prefixes to test (JSON array). Prefix testing catches hardcoded table names — keep enabled. Pass `'[""]'` to test without a prefix only. | `'["", "flarum_"]'` |
| `backend_directory` | Directory containing `composer.json` | `"."` |
| `runner_type` | GitHub Actions runner type | `"ubuntu-latest"` |
| `php_extensions` | PHP extensions to install (comma-separated) | `"curl, dom, gd, json, mbstring, openssl, pdo_mysql, pdo_pgsql, tokenizer, zip"` |
| `php_ini_values` | PHP ini values (comma-separated) | `"error_reporting=E_ALL"` |
| `fail_fast` | Cancel remaining matrix jobs if any job fails | `true` |

### Secrets

All secrets are optional.

| Secret | Description |
| --------------- | ---------------------------------------- |
| `composer_auth` | Composer auth token for private packages |

:::tip

For more details on parameters, [checkout the full predefined reusable workflow file](https://github.com/flarum/framework/blob/main/.github/workflows/REUSABLE_backend.yml).
For more details, see the [full reusable workflow file](https://github.com/flarum/framework/blob/2.x/.github/workflows/REUSABLE_backend.yml).

:::

Expand Down Expand Up @@ -95,7 +104,7 @@ jobs:
Unlike the backend workflow, the frontend workflow runs everything in a single job. Here are the available parameters:

| Name | Key | Description | Format |
|-----------------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------|
| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Build Script | `build_script` | Script to run for production build. Empty value to disable. | string |
| Build Typings Script | `build_typings_script` | Script to run for typings build. Empty value to disable. | string |
| Format Script | `format_script` | Script to run for code formatting. Empty value to disable. | string |
Expand All @@ -112,6 +121,7 @@ Unlike the backend workflow, the frontend workflow runs everything in a single j
| Node Version | `node_version` | The node version to use for the workflow. | string |
| JS Package Manager | `js_package_manager` | The package manager to use (ex. yarn) | string |
| Cache Dependency Path | `cache_dependency_path` | The path to the cache dependency file. | string |

:::tip

For more details on parameters, [checkout the full predefined reusable workflow file](https://github.com/flarum/framework/blob/main/.github/workflows/REUSABLE_frontend.yml).
Expand Down
3 changes: 3 additions & 0 deletions docs/extend/update-2_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -655,3 +655,6 @@ PHPUnit 12 emits a notice for every mock that is created without any expectation

##### <span class="breaking">Breaking</span>
* The reusable GitHub workflows must be updated to use target the ones from the **2.x** branch. For example, you must change `flarum/framework/.github/workflows/REUSABLE_backend.yml@main` to `flarum/framework/.github/workflows/REUSABLE_backend.yml@2.x`.

##### <span class="notable">Notable</span>
* The default database versions tested by the [backend workflow](github-actions.md#backend) have been updated to `mysql:9.7`, `mariadb:12.3`, `postgres:18`, and `sqlite:3`. If your extension needs to test against a different set of versions, pass the `db_versions` input in the `with` section of your workflow file.