Debugging GitHub actions, or any kind of CI runner, is time consuming. I usually mess up secrets that depend on exact structure, like private keys.

First tip: use base64 to encode and decode secrets. Also, watch out for new lines, extra spaces at the end. They can break things.

To encode and copy a file:

cat supersecretfile.json | base64 | clip # windows
cat supersecretfile.json | base64 | pbcopy # linux or macos

encode secret

To decode:

echo $SECRET_BASE64 | base64 -d

decode secret

Tmate helps with debugging

Best way to check what's wrong is to compare the credentials via ssh. I use tmate, a tool that lets you share a remote terminal session. You run it, it gives you a secure ssh link. Someone else can use it to connect and see or control your terminal.

Debug GitHub Actions

To use tmate in github actions, just add these two lines in your workflow file:

- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3

Run the action. When it hits that step, you'll get a unique ssh link. Use it to ssh into the runner and debug.

Important:

  • Do not forget to cancel your GitHub action run to avoid a bigger GitHub bill at the end of the month.
  • Do not use this on your public repos. Once you can see the ssh link in your public GitHub action, everyone else on the internet can see it too.

Running GitHub Actions locally would help too, but that’s a topic for another post.

Youtube: https://youtu.be/a7eZBWh3Z8Q