Make it easier to debug GitHub Actions

A failing pipeline can be an annoying thing to troubleshoot. Personally, I've had minimal success with tools like act which let you run your GitHub Actions locally.

So often we're forced to guess what went wrong, make a tweak, push it, and wait for CI to fail again. Rinse and repeat maybe a dozen times.

This is time-consuming when working on the pipeline itself, but it's also an issue when you have a test failing in CI that isn't failing locally.

There are two things I add to every GitHub Actions pipeline to make debugging easier, and both use the failure() status check function.

First, right after spinning up my Docker containers in the action, I add this block:

- name: Docker startup failure
  if: ${​{ failure() }}
  run: |
    docker ps -a
    docker logs --timestamps "$PROJECT_NAME-php-fpm"
    docker logs --timestamps "$PROJECT_NAME-mysql"
    docker inspect "$PROJECT_NAME-php-fpm"
    docker inspect "$PROJECT_NAME-mysql"

So if something went wrong with building or starting the Docker containers, I can see the logs and inspect the containers.

Second, I use this block after running tests:

- name: Test failure
  if: ${​{ failure() }}
  run: docker exec "$PROJECT_NAME-php-fpm" cat storage/logs/laravel.log

I would say that over half the time, these two status check blocks lead me to a solution without having to dig any further.

Read more on other available status check functions in the GitHub Actions documentation.

Here to help,

Joel

P.S. We had a great discussion on debugging CI pipelines on the latest Mastering Laravel community dev call. Join us for the next one!