DEV Community

Cover image for GitHub Actions for Laravel: Run Tests with PHP Matrix, MySQL
devTalk
devTalk

Posted on Originally published at dev-talk.com

GitHub Actions for Laravel: Run Tests with PHP Matrix, MySQL

Last updated: 12 November 2026. See theupdate logat the end.

A Laravel test suite that only runs on your laptop will eventually fail on the server for a reason you cannot reproduce: a missing PHP extension, a different PHP version, or a MySQL behavior that SQLite hides. A CI workflow fixes that by running the same checks in a clean machine on every push and pull request. This is Part 1 of a three-part series on a Laravel pipeline in GitHub Actions:

  1. Part 1 (this article): run the tests on a PHP version matrix with a MySQL service.
  2. Part 2: cache Composer and npm so runs are faster.
  3. Part 3: deploy over SSH with releases, an atomic switch and rollback.

The workflow below passes actionlint and GitHub's workflow schema check, and its shell steps were run locally against a real MySQL server on Laravel 13.40.0. I could not run php artisan test itself or the workflow on GitHub's runners, and the "How this was checked" section at the end lists exactly what that means.

The workflow

Save this as .github/workflows/ci.yml:

name: Tests

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  tests:
    name: PHP ${{ matrix.php }}
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        php: ['8.3', '8.4']

    services:
      mysql:
        image: mysql:8.4
        env:
          MYSQL_ROOT_PASSWORD: password
          MYSQL_DATABASE: testing
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping -ppassword"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=5

    env:
      DB_CONNECTION: mysql
      DB_HOST: 127.0.0.1
      DB_PORT: 3306
      DB_DATABASE: testing
      DB_USERNAME: root
      DB_PASSWORD: password

    steps:
      - name: Check out code
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: mbstring, pdo_mysql, zip, pcntl
          coverage: none

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

      - name: Prepare the application
        run: |
          cp .env.example .env
          php artisan key:generate

      - name: Run tests
        run: php artisan test
Enter fullscreen mode Exit fullscreen mode

What each part does

Triggers, permissions and concurrency

  • on: push to main plus pull_request gives you a check on every PR and on every merge.
  • permissions: contents: read limits what the job's GITHUB_TOKEN can do. Laravel's own starter workflow sets the same thing. Tests only need to read the code.
  • concurrency groups runs by workflow and branch. GitHub's docs say a group holds at most one running and one pending run, and that cancel-in-progress: true also cancels the one that is running. Here that applies to pull requests only, so a new push to a PR cancels the stale run, while runs on main are never cancelled. That matters in Part 3, when main pushes start deployments.

The matrix

matrix.php runs the job once per PHP version. Laravel 13 requires PHP 8.3 or newer, so 8.3 and 8.4 are a sensible floor and a current version; Laravel's own starter workflow also includes 8.5, and you can add it. fail-fast: false lets every version finish, so one failure doesn't hide a second one on another version.

The MySQL service container

GitHub starts mysql:8.4 next to the job. Because the job runs directly on the runner and not in a container, the docs say you reach the service at localhost (or 127.0.0.1) on the mapped port, which is why ports maps 3306 and DB_HOST is 127.0.0.1. The options block is the health check pattern from GitHub's service container docs (their example uses PostgreSQL and pg_isready; I adapted it to mysqladmin ping). Without it, the first test can start before MySQL accepts connections and fail with a connection error.

Pick the MySQL image tag that matches production. If you run MariaDB, use the MariaDB image and its own health command instead.

setup-php

shivammathur/setup-php installs the PHP version and extensions and a current Composer by default. coverage: none disables Xdebug and PCOV; the action's README notes that Xdebug is enabled by default on Ubuntu images and recommends turning it off if you don't need coverage, which speeds up PHP. Add pdo_mysql and anything else your app needs to the extensions list. The extension list is where "works locally, fails in CI" most often starts.

checkout and persist-credentials

actions/checkout normally leaves the auth token in the local git config for the rest of the job, so scripts can run authenticated git commands. persist-credentials: false opts out. Your tests don't push to the repository, so there is no reason to keep it.

Check the database setup before trusting it

The Prepare the application step and a migration run were executed against a local MySQL server with the same environment variables the job sets (the port was 3307 locally, not 3306):

   INFO  Application key set successfully.

Creating migration table ...................................... DONE
0001_01_01_000000_create_users_table .......................... DONE
0001_01_01_000001_create_cache_table .......................... DONE
0001_01_01_000002_create_jobs_table ........................... DONE
2026_11_08_000001_add_is_admin_to_users ....................... DONE
tables: cache cache_locks failed_jobs job_batches jobs migrations password_reset_tokens sessions users
Enter fullscreen mode Exit fullscreen mode

That confirms the .env.example copy, key generation and the DB_* variables reach MySQL. One gotcha is worth checking in your own repository: the phpunit.xml in the Laravel starter project sets DB_CONNECTION to sqlite and DB_DATABASE to :memory:. If you want your tests to run on the MySQL service, remove or comment out those two lines (or use a separate phpunit.ci.xml and pass it to PHPUnit). I did not run PHPUnit, so I can't tell you which value wins if both are present. Don't leave it to chance: the fix above is unambiguous.

Also decide which database you want. SQLite in memory is faster and is a fine default for most suites. MySQL in CI is worth it when your code depends on MySQL behavior: JSON columns, full-text search, collations, or raw queries.

Common mistakes

  • Nocomposer.lockcommitted. CI then installs whatever versions are newest that day. Commit the lock file for applications.
  • Missing PHP extension. Add it to extensions; don't install it from a shell step.
  • Using the service name as the host. DB_HOST: mysql works only when the job itself runs in a container. On the runner, use 127.0.0.1 with a mapped port.
  • Skipping the health check. Intermittent connection errors at the start of the run usually mean the database wasn't ready.
  • Putting real credentials in the workflow. The MySQL password above is a throwaway for a container that disappears after the job. Real secrets belong in GitHub's secrets store (Part 3).

Alternatives

  • SQLite only: remove the services block and the DB_* variables and keep Laravel's default phpunit.xml. Simplest and fastest.
  • Parallel tests: php artisan test --parallel if your suite supports it. Test it locally first; shared databases need care.
  • Static analysis and style checks: add Pint or PHPStan as separate jobs so a style failure doesn't hide a test failure.

Related Dev Talk articles

Frequently asked questions

Do I need a matrix?

Only if you support more than one PHP version. If production runs one version, test that one, and add the next version when you plan to upgrade.

Why cp .env.example .env in CI?

.env is not committed. The example file gives Laravel a baseline, key:generate adds an application key, and the job-level DB_* variables are already in the process environment.

Can I run the workflow locally?

Tools like act exist for that. I did not test one. What I did instead was run each shell step locally and lint the file, which catches most mistakes before a push. actionlint is a quick linter for workflow files.

Should lint and static analysis run in the same job?

Separate jobs are easier to read: a style failure then doesn't hide a test failure, and the jobs run in parallel. The trade-off is one more runner start-up per job.

Update log

  • 12 November 2026: first version.
  • To recheck on each update: the major versions of actions/checkout and shivammathur/setup-php, the PHP versions in Laravel's own tests.yml, the default phpunit.xml database lines, and the Actions concurrency docs.

Sources


Originally published on DEV Talk.

Top comments (0)