SSH into running jobs to debug issues, inspect state, or troubleshoot your workflows in real-time. Access is automatically granted using the SSH keys from your GitHub account. Zero configuration required.

​
How it works

When a job starts on a Blacksmith runner, SSH access is automatically enabled. The runner authorizes connections using the SSH keys you’ve added to your GitHub account, ensuring secure access without any additional setup. Each runner exposes a unique SSH port that’s displayed in your workflow logs at the start of every job.

​
Connecting to a runner

At the beginning of each job, you’ll see connection information in the Setup runner step: 
ssh -i ~/.ssh/id_ed25519 -p 12345 runner@...
Simply copy and run the command in your terminal to connect.

​
Simplify connections with SSH config

Add this to your ~/.ssh/config file to streamline connections: 
Host *.vm.blacksmith.sh
    IdentityFile ~/.ssh/id_ed25519
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
With this configuration, you can connect using just: 
ssh -p 12345 runner@...
The StrictHostKeyChecking no and UserKnownHostsFile /dev/null settings skip host key verification since runner VMs are ephemeral and get new host keys each time. This also avoids cluttering your known_hosts file with temporary VM fingerprints.

​
Common use cases

​
Debug failing tests

Connect to inspect test artifacts, environment variables, or running processes when tests fail unexpectedly.

​
Verify build outputs

Check generated files, build artifacts, or compilation outputs directly on the runner.

​
Inspect environment state

Examine installed dependencies, system configurations, or runtime environments during workflow execution.

​
Troubleshoot network issues

Test connectivity, DNS resolution, or API access from within the runner environment.

​
FAQ

How do I keep a job running for debugging? Add a sleep step that runs on failure to give yourself time to connect and debug: 
- name: Keep job alive on failure for debugging
  if: failure()
  run: |
    echo "Job failed. Keeping VM alive for 30 minutes for debugging..."
    echo "SSH connection info is available in the Setup runner step above"
    sleep 1800
We don’t recommend using the action-tmate step as it’s unnecessary with Blacksmith’s built-in SSH support, and adds complexity to your workflow.
Why am I getting “Could not resolve hostname”? This error means the job has already finished. SSH access is only available while the job is actively running. Add a sleep step (see above) to keep the job alive longer. Why am I getting “Permission denied”? Verify that:
  • Your SSH key is properly added to your GitHub account
  • You’re using the correct key file path (usually ~/.ssh/id_ed25519)
  • You’re the person who triggered the job (only the job sender can SSH in)
Can multiple people SSH into the same runner? No, only the GitHub user who triggered the job can SSH into the runner. We’re planning to add support for configuring additional SSH keys on demand through environment variables in your jobs. This will provide a secure way to grant access to team members when needed. Stay tuned for updates! How long can I stay connected? You can stay connected as long as the job is running. If you’re still connected when the job completes, we provide a grace period of approximately 5 minutes before terminating the connection. Is there any additional cost for SSH access? No, SSH access is automatically enabled for all Blacksmith runners at no additional cost. It’s included as a standard feature.

​
Support

Need help with SSH access? Let us know by opening a support ticket.