Skip to content
RunsOn
Blog

Debugging GitHub Actions

Debugging GitHub Actions can be challenging due to their remote execution nature. However, several strategies can help you identify and resolve issues effectively.

Using Act for local testing

Act ↗ is a powerful tool that allows you to run your GitHub Actions locally:

  1. Install Act following the official instructions ↗
  2. Run your workflow locally:
Terminal window
act -j <job_name>

This approach helps catch issues before pushing to the remote repository.

Some limitations of Act:

  1. Environment differences: Act uses Docker containers, which may not perfectly replicate the GitHub-hosted runner environment.

  2. Limited secrets and environment variables: You’ll need to manually set up secrets and environment variables locally.

  3. Incomplete action support: Some actions, especially those interacting with GitHub’s API, may not work as expected in the local environment.

  4. Resource intensive: Running complex workflows locally can be demanding on system resources.

  5. Maintenance: You need to keep Act updated to ensure compatibility with the latest GitHub Actions features.

Despite these drawbacks, Act remains a useful tool for initial debugging and testing of workflows.

Using tmate for interactive debugging

For more complex issues, tmate ↗ allows you to access the runner environment directly. This tool creates a secure, instant terminal sharing session, enabling you to interact with the live runner environment as if you were physically present. You can inspect files, run commands, and debug issues in real-time. The mxschmitt/action-tmate ↗ GitHub Action is a popular choice for this purpose.

  1. Add this step to your workflow:
- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  1. When the action runs, inspect the workflow logs and you’ll get an SSH command to connect to the runner. After that, you can run any commands in the runner environment.

Direct SSH connection to the runner

RunsOn allows you to connect to the runner environment directly. This can be useful for inspecting files, running commands, and debugging issues in real-time. More details in the SSH section. Other providers may offer similar features.