How to Debug GitHub Actions for Real-Time Troubleshooting?

name: tmate debug session
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup tmate session
      uses: mxschmitt/action-tmate@v3

action-tmate

Debug your GitHub Actions via SSH by using tmate to get access to the runner system itself.

tmate GitHub Action pretty handy for debugging issues directly on the host where GitHub Actions are running. It's kind of like having a remote desktop, but through SSH or a web terminal.

This tool seems incredibly useful for anyone needing to troubleshoot or debug their CI workflows in real time. It provides a way to jump into the actual environment where the actions are executed, which is a game changer for debugging complex issues. Plus, the flexibility to use it only when needed or in a secured manner with SSH keys makes it both practical and secure.

Key Points:

1. Direct Debugging: You can start a tmate session through your workflow to interact with the host system either via SSH or a web shell. Once you're done, you can simply continue your workflow.
2. Supported OS: It works on Linux, macOS, and Windows.
3. Easy Setup: The setup is straightforward. Here's a minimal example: it triggers on a 'push' event, checks out your repository, and sets up a tmate session.
4. Flexibility in Debugging: You can trigger debugging manually with a workflow_dispatch event, allowing you to enable debugging on the fly without changing your workflow file continuously.
5. Detached Mode: This feature starts the tmate session and proceeds with the workflow unless you interact; if not, it closes after a set timeout.
6. Security Options: You can limit session access to only those with a registered public SSH key, enhancing security.
7. Customization: It supports custom tmate servers if you don’t want to use the default provided servers.

How to Manually Trigger Debugging in GitHub Actions with Tmate?​

When you need to debug your GitHub Actions without constantly modifying your configuration or pushing commits, you can use a manually triggered debug approach. This method involves setting up an optional parameter through a workflow_dispatch event, which allows you to activate debugging when needed.

Step-by-Step Guide:

1. Set Up the Trigger: In your GitHub Actions workflow file, define a workflow_dispatch event. This allows you to manually trigger the workflow from GitHub's interface. Add inputs under this event to control the debug mode:

   on:
     workflow_dispatch:
       inputs:
         debug_enabled:
           type: boolean
           description: 'Run the build with tmate debugging enabled'
           required: false
           default: false
   

   This setup introduces an input debug_enabled which can be toggled when you manually dispatch the workflow.

2. Conditional Debug Step: Within the jobs of your workflow, add a condition to the step that sets up the tmate session. This condition checks if the debug_enabled input is true:

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - name: Setup tmate session
           uses: mxschmitt/action-tmate@v3
           if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
   

   This configuration means the tmate session is only initiated if the workflow is manually triggered with the debug enabled.

Advanced Debugging Modes:

• Detached Mode: Set up your workflow to start a tmate session in detached mode. This means the session will start and provide connection details, but your workflow will continue running the subsequent steps without waiting for you to connect:

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

  The session will automatically terminate if no connection is made within a predefined timeout period.

• Handling Permissions: To ensure that only authorized users can access the tmate session, you might want to restrict it to those with specific SSH keys:

  - name: Setup tmate session
    uses: mxschmitt/action-tmate@v3
    with:
      limit-access-to-actor: true
  

  This setup requires users to have a registered public SSH key to connect.

How to Configure Your Own Tmate Server?​

If you prefer not to use the default tmate server, you can specify your own server details:

- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  with:
    tmate-server-host: your-custom-tmate-server.com
    tmate-server-port: your-port
    tmate-server-rsa-fingerprint: your-rsa-fingerprint
    tmate-server-ed25519-fingerprint: your-ed25519-fingerprint

Skipping Tmate Installation:

In cases where you are using self-hosted runners and do not need to install tmate or its dependencies, you can skip this step:

- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  with:
    install-dependencies: false

This method of debugging is highly efficient for testing and fixing workflows without affecting the main configuration or workflow logic. It provides flexibility and security, making it an invaluable tool for developers working with complex GitHub Actions workflows.