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:
- Part 1 (this article): run the tests on a PHP version matrix with a MySQL service.
- Part 2: cache Composer and npm so runs are faster.
- 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
What each part does
Triggers, permissions and concurrency
-
on: pushtomainpluspull_requestgives you a check on every PR and on every merge. -
permissions: contents: readlimits what the job'sGITHUB_TOKENcan do. Laravel's own starter workflow sets the same thing. Tests only need to read the code. -
concurrencygroups runs by workflow and branch. GitHub's docs say a group holds at most one running and one pending run, and thatcancel-in-progress: truealso 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 onmainare never cancelled. That matters in Part 3, whenmainpushes 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
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
-
No
composer.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: mysqlworks only when the job itself runs in a container. On the runner, use127.0.0.1with 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
servicesblock and theDB_*variables and keep Laravel's defaultphpunit.xml. Simplest and fastest. -
Parallel tests:
php artisan test --parallelif 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
- GitHub Actions for Laravel, Part 2: Cache Composer and npm
- GitHub Actions for Laravel, Part 3: Deploy over SSH with Releases and Rollback
- Laravel .env Configuration: env() vs config()
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/checkoutandshivammathur/setup-php, the PHP versions in Laravel's owntests.yml, the defaultphpunit.xmldatabase lines, and the Actions concurrency docs.
Sources
- actions/checkout README
- shivammathur/setup-php README
- laravel/laravel: tests.yml and phpunit.xml
- GitHub Docs: Creating PostgreSQL service containers
- GitHub Docs: Control the concurrency of workflows and jobs (Enterprise Server 3.14 page)
- actionlint
Originally published on DEV Talk.
Top comments (0)