SSH into your Gitea Actions for debugging

While Gitea Actions allows for local debugging of workflows, sometimes you need to debug directly on the runner. This is especially challenging since the workflows only exist for the duration of the run. Even if you have access to the server and can docker exec into the container, it may terminate while you are debugging.

Since Gitea Actions are compatible with GitHub Actions, you can use action-tmate to SSH directly into the runner environment, and debug your workflow in real-time.

Adding action-tmate to your workflow

First, edit your Gitea Actions workflow YAML to add the action-tmate step.

name: CI
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # Add this step wherever you need debugging access
      - name: Debug with SSH
        uses: mxschmitt/action-tmate@v3

When this step runs, it will pause the workflow and output SSH connection details in the logs. The workflow will wait until you’ve connected, finished debugging, and exited the session. However, if you place this step after a failing one, the workflow may stop before reaching it.

Connecting to your runner

Once the action runs, check your workflow logs. You’ll see connection details like:

WebURL: https://tmate.io/t/...
SSH: ssh abc123...@...tmate.io

You can connect using either SSH or the web interface. The web interface is especially useful if your network’s firewall blocks SSH connections.

Once connected, you’ll have full shell access to the runner environment, allowing you to inspect files, run commands, and verify network connectivity.

When you’re done debugging, exit the SSH session and then the workflow will continue with the next step after the action-tmate step.

Security: Remember that SSH access is public (if someone gets the link), so don’t leave it idle for too long.

Targeted debugging approaches

You probably don’t want to SSH into every workflow run. Here are some more practical approaches:

Only on failure:

- name: Debug with SSH
  if: ${{ failure() }}
  uses: mxschmitt/action-tmate@v3

This only activates the SSH session if a step in the workflow failed.

Manual trigger:

With the introduction of workflow_dispatch in Gitea 1.24, you can manually trigger workflows, and have an option to enable SSH debugging:

on:
  workflow_dispatch:
    inputs:
      debug_enabled:
        type: boolean
        description: 'Enable SSH debugging'
        required: false
        default: false

# Then in your job:
steps:
  - name: Debug with SSH
    if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
    uses: mxschmitt/action-tmate@v3

Conclusion

There are a lot of ways to debug failing workflows, but nothing beats direct access to the exact environment where the workflow is running. action-tmate provides many other advanced configuration options as well that you can investigate.

Adding action-tmate to your workflow#

Connecting to your runner#

Targeted debugging approaches#

Only on failure:#

Manual trigger:#

Conclusion#