Troubleshooting Ubicloud GitHub Actions Runners

Most Ubicloud runner problems trace back to the label, network access, or needing to see what happened inside a failed job.

This guide covers the issues teams most often hit with Ubicloud GitHub Actions runners, grounded in Ubicloud's own docs. For anything beyond these, check Ubicloud's documentation, since behavior and options change.

Job stuck "Waiting for a runner"

If a job hangs waiting to be picked up, the most common cause is a runs-on label that does not match a Ubicloud runner you have access to. Confirm the label (for example ubicloud-standard-2) exactly matches one from Ubicloud's docs, and that the Ubicloud Managed Runners GitHub App is installed on that repository. Verify the current label list on Ubicloud's docs.

Cannot reach a firewalled service

According to Ubicloud's docs, if your workflow accesses services behind a firewall you may need to allowlist Ubicloud's IP ranges, which they publish at api.ubicloud.com/ips-v4. Add those ranges to the allowlist on the service side, then re-run the job.

Debugging a failed job by SSH

Ubicloud publishes an open-source ubicloud/ssh-runner action to SSH into a managed runner during a workflow for debugging. Per its README, you add it as a step with your public SSH key and a wait window; the runner stays reachable for the configured minutes or until the workflow finishes, whichever comes first. Ubicloud's guidance is to use it for debugging only and never expose your private key.

Debug step (per ubicloud/ssh-runner docs)

- name: SSH access on failure (debug only)
  if: ${{ failure() }}
  uses: ubicloud/ssh-runner@v2
  with:
    public-ssh-key: ${{ secrets.SSH_PUBLIC_KEY }}
    wait-minutes: 30

Recurring transient failures (OOM, disk full, registry timeouts)

If the same jobs fail intermittently on infrastructure causes rather than real test failures, that is a category no label change fixes on its own; you re-run and hope. This is exactly what Latchkey's self-healing runners target: transient and mechanical failures are detected, fixed, and retried automatically. If flaky re-runs are your main Ubicloud pain, it is worth benchmarking Latchkey on the same workflow.