Github Actions Gotchas

It can be tricky to debug GitHub Actions. Although GitHub Actions Documentation is well organized, it’s light on details. The docs do not always expound on common pitfalls developers might run into.

Here are some issues( and solutions) to be aware of when using GitHub Actions for DevOps or other projects.

Passing Dynamic Values for Reusable Actions

When working with reusable actions, you may need to pass dynamic values between steps or jobs. There are several ways to accomplish this:

Expanding or adding matrix configurations – If you have a set of values that need to be passed to multiple jobs, you can use a matrix. This is especially useful when testing across different platforms or environments.

Store in variables (not secrets): Use variables to store dynamic values and pass them between jobs and steps. Remember that secrets are not suitable for this purpose, as they are designed for storing sensitive data, and their usage is limited.

JSON object: You can also use a JSON object to store your dynamic values, which can then be used with GitHub Actions expressions. For example, follow the guide on returning a JSON object in GitHub Actions.

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: build

Enable Logging

To enable better logging, follow the official guide on enabling debug logging in GitHub Actions. This will help you gain insights into what’s happening behind the scenes, making it easier to identify issues and fix them.

Use tmate

Debug your workflow in real-time with the mxschmitt/action-tmate action. It allows you to SSH into the runner and manually execute commands, inspect the environment, and even interact with the file system. To use Tmate effectively, remember to:

SSH into the session and manually run the failing commands.
Run sh, or ensure you are using the same shell as the action, to avoid potential issues caused by using a different shell.

Mind the Shell

GitHub Actions use sh (Bourne shell) by default, which may cause issues with certain shell-specific syntax. For example, outputting stdout and stderr to a file using &>> will not work in sh and may result in vague error messages. These commands work fine in bash and other more feature-rich shells.

To avoid such issues, you can either:

Modify your shell commands to work with sh.
Change the default shell for your workflow to a more feature-rich shell, like bash.

Remember that error messages may not be very helpful in identifying such issues, so always keep in mind the shell being used in your workflow.

In conclusion, while GitHub Actions is a powerful tool for automating your software development processes, it’s essential to be aware of these common pitfalls. By passing dynamic values correctly, enabling logging, using Tmate for real-time debugging, and minding the shell, you can overcome these challenges and make your experience with GitHub Actions more enjoyable and productive.

Using Act for Local Testing

Before pushing your changes to your GitHub repository, it’s often helpful to test your GitHub Actions workflows locally. One way to do this is by using act, a tool that allows you to run your GitHub Actions locally using Docker containers. This can help you catch errors, validate your workflows, and ensure everything is working as expected before making your changes live.

To use act, you need to:

Install Docker on your local machine.
Install act following the instructions on the official repository.
Navigate to your project directory, where your .github/workflows folder is located.
Run the act command, which will execute your workflows using the specified GitHub Actions environment.

By using act to test your workflows locally, you can avoid introducing errors into your repository and ensure your GitHub Actions are working as intended. This can save time and resources and help maintain a high level of quality in your CI/CD processes.

If you have the space to spare and need access to a wide range of software in your workflows, consider using the 40GB full featured docker images from catthehacker/docker_images as default image for runners. You could then specify the runner to use with:

act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:full-20.04

This will ensure all ensure that popular apps like node and jq will be available in the runner if you need to use these in actions.

Handling Contexts and Avoiding ‘Unrecognized named-value: ‘env” Errors.

Contexts provide access to various data, including environment variables, job outputs, and more. Incorrect usage of contexts can lead to errors(
For example,
‘Unrecognized named-value: ‘env” error for jobs.<job_id>.container.

There are a number or workarounds to retrieve the value of a variable from an inaccessible context, such as Defining outputs for jobs.

If all else fails, check Stack-overflow and Github Issues, someone is is bound to have already has some version of the issue you face.

Despite the odd idiosyncrasy and sometimes unintuitive behavior you may face when getting used to Github Actions features, is a powerful tool with a quick learning curve( especially for anyone comfortable with bash/shell scripting ).

Dev Unstuck