Continuous integration

The monorepo's own CI (.github/workflows/ci.yml) only validates every composer manifest (root metapackage + every packages/* + plugins/*). It deliberately does not composer install: the root is a metapackage over the full private flyokai/* graph (self.version siblings + private cluster packages + the external forks), which is not resolvable on a stock runner — see composer-repositories.md. It runs one job: composer validate --strict --no-check-lock over each manifest.

Per-module install / lint / tests belong in each split repo. Copy the reference workflow below into a flyokai/* module's .github/workflows/ci.yml and adapt as needed.

What the reference (per-module) workflow runs

Step	What it does	When it fails
composer validate --strict	Lints composer.json (well-formed, license, no missing fields)	Always — every PR
composer install --prefer-dist	Resolves dependencies, generates autoload	Every PR
composer run cs-check	Coding-style check (only if defined in the module's composer.json)	Soft — skipped if absent
composer test	PHPUnit (only if defined in the module's composer.json)	Soft — exits 0 if absent (until tests are added)

The matrix runs on PHP 8.2 and 8.3 by default — adjust per module.

name: CI

on:
  push:
    branches: [dev, main]
  pull_request:
    branches: [dev, main]

jobs:
  test:
    name: PHP ${{ matrix.php }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest]
        php: ["8.2", "8.3"]

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          tools: composer:v2
          extensions: mbstring, intl, pdo_mysql, mysqli, openssl, zip
          coverage: none

      - name: Cache composer
        uses: actions/cache@v4
        with:
          path: ~/.cache/composer/files
          key: composer-${{ matrix.php }}-${{ hashFiles('**/composer.json') }}
          restore-keys: composer-${{ matrix.php }}-

      - name: Validate composer.json
        run: composer validate --strict

      - name: Install dependencies
        run: composer install --prefer-dist --no-progress

      - name: Lint
        run: |
          if composer run --list | grep -q '\bcs-check\b'; then
            composer run cs-check
          else
            echo "no cs-check script — skipping"
          fi

      - name: Tests
        run: |
          if composer run --list | grep -q '\btest\b'; then
            composer test
          else
            echo "no test script — failing soft until tests are added"
            exit 0
          fi

Adding tests to a module

Add this to the module's composer.json:

{
    "require-dev": {
        "phpunit/phpunit": "^9.6 || ^10.5"
    },
    "scripts": {
        "test":  "phpunit --colors=always",
        "test-coverage": "phpunit --coverage-clover=clover.xml"
    }
}

Add a phpunit.xml.dist:

<?xml version="1.0"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.6/phpunit.xsd"
         colors="true"
         bootstrap="vendor/autoload.php"
         cacheResultFile=".phpunit.cache/test-results"
         executionOrder="depends,defects"
         beStrictAboutOutputDuringTests="true">
    <testsuites>
        <testsuite name="unit">
            <directory>test/</directory>
        </testsuite>
    </testsuites>
</phpunit>

Tests live under test/. Use the namespace Flyokai\<Module>\Test\.

DB-touching tests

For modules that hit MySQL (driver-amp, driver-async, db-schema, search-criteria, indexer, oauth-server, user, application):

services:
  mysql:
    image: mysql:8.0
    env:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: flyokai_test
    ports:
      - 3306:3306
    options: >-
      --health-cmd="mysqladmin ping" --health-interval=10s
      --health-timeout=5s --health-retries=3

Pass connection details to the test bootstrap via env vars (DB_HOST, DB_NAME, DB_USER, DB_PASS).

OpenSearch-touching tests

For flyokai/amp-opensearch:

services:
  opensearch:
    image: opensearchproject/opensearch:2.11.1
    env:
      discovery.type: single-node
      DISABLE_SECURITY_PLUGIN: "true"
    ports:
      - 9200:9200

Badges

Once CI is wired:

[![CI](https://github.com/flyokai/<module>/actions/workflows/ci.yml/badge.svg)](https://github.com/flyokai/<module>/actions/workflows/ci.yml)

Drop this at the top of the module's README.md, just under the # title.

Coverage

Coverage uploads to Codecov / Coveralls are intentionally not in the reference workflow — the framework predates a coverage strategy. Add per-module if you want it.