How do I connect to a database using Laravel in a GitHub Action?

The Problem

You can automatically run your unit tests when committing your Laravel project to GitHub by using a GitHub Actions workflow. The workflow is configured in a .yaml file in your repository’s .github/workflows folder.

Your unit tests will need a database to run against. How can I set this up in a GitHub workflow?

The Solution

GitHub includes a MySQL and PostgreSQL database in their test runner. Let’s look at how to use it.

To run a GitHub Action when you commit your code, create the file .github/workflows/test.yaml.

Insert the following content:

name: Test Laravel
on:
    push:
        branches:
            - main
    workflow_dispatch:

The code above sets the name of the workflow that will display in the Actions tab of your GitHub repository, then sets two events on which the workflow will run:

• When pushing to the main branch.
• When manually triggered from the GitHub Actions web page.

Next, add the code below which specifies what will run when these events trigger:

jobs:
    run-tests:
        runs-on: ubuntu-latest

        steps:
            - name: Checkout repository
              uses: actions/checkout@v4

            - name: Install PHP latest
              run: |
                  sudo apt remove php -y
                  sudo apt update
                  sudo add-apt-repository ppa:ondrej/php
                  sudo apt update
                  sudo apt -y install php
                  sudo apt update
                  sudo apt install php-curl php-xml php-mbstring php-mysql -y

            - name: Start Mariadb
              run: |
                  sudo systemctl start mysql.service
                  mysql -uroot -proot -e 'CREATE DATABASE IF NOT EXISTS laravel;'

            - name: Install Composer dependencies
              run: composer update

            - name: Run unit tests
              run: |
                  php artisan migrate
                  php artisan test

The only job in this workflow is run-tests set to run on a Linux machine. There are five steps:

• Checkout your code on the GitHub runner (virtual machine).
• Install the latest version of PHP and common dependencies.
• Start MySQL.
• Install the Laravel dependency packages.
• Run your unit tests.

GitHub provides a test runner environment based on Ubuntu Linux with some extra features. For a full overview, see this documentation.

Note that the MySQL username and password are root. Set these in your .env file to run the test in an experimental project, or use GitHub secrets when running in production (where you don’t want to commit your .env file secrets to version control).

The Ubuntu 22.04 image uses PHP 8.1, so in this script, we install the latest available PHP version in the PPA ppa:ondrej/php manually (8.3 at the time of writing). You could also install PHP by searching for a PHP Action either from GitHub, or on the Actions Marketplace. In the configuration, you can also use an Action for a different database like PostgreSQL.

Save the test.yaml file, commit it, and push it to GitHub. On the Actions tab of your repository you can see your tests run.