Debugging Github Actions

I’ve been using Github Actions to create CI/CD pipelines for a new project. In the process of setting it up, I ran into an issue familiar to anyone who’s worked with CI/CD systems before: builds failing due to missing external dependencies in the virtual environment used by the CI/CD system. The project had some complex application dependencies that I need to replicate from the local development environment (OS X) into the build environment (Ubuntu).

Normally, the approach to fixing this problem is as follows….

  1. Google around for a random Stack Overflow suggestion on which packages you need to install.
  2. Update build file, git push the changes and re-run build.
  3. 🤞Cross fingers and hope it works. If it is still broken, goto 1.

This can be a frustrating process when you have complex builds or slow CI/CD environments. Luckily, I was using Github Actions and found a better way:

docker run -it -v $(pwd):/app/ nektos/act-environments-ubuntu:18.04

This command gave me a shell in a reproduction of the virtual environments used by Github Actions. My local project files were mapped into the /app/ directory. I could then apt-get install packages and re-run the make commands quickly to investigate the build issue. This was a much faster debugging cycle than triggering the external CI/CD system each time.

These Docker images came from a project to run Github Actions locally (nektos/act). This project builds and publishes the virtual environments used in Github Actions as public Docker images.

Having fixed the issue locally, the Github Actions workflow file could then be updated to include the missing dependencies and the build was fixed. Voilà 😘.