​
Overview

SSH into running jobs to debug issues, inspect state, or troubleshoot your workflows in real-time. When enabled by your organization admin, access is granted to job triggerers using their GitHub SSH keys.
SSH access is opt-in and must be enabled by a GitHub organization admin from the Settings > Features page before it can be used.

​
Basics

When SSH access is enabled for your organization and a job starts on a Blacksmith runner, the runner authorizes connections using the SSH keys you’ve added to your GitHub account.
Access requirements:
  • SSH access must be enabled by an organization admin
  • Only the GitHub user who triggered the job can SSH into the runner
  • You must be a member of the GitHub organization
  • SSH keys must be configured in your GitHub account
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 -p 12345 runner@...
Simply copy and run the command in your terminal to connect using your GitHub SSH key.

​
Simplify connections with SSH config

Add this to your ~/.ssh/config file to streamline connections: 
Host *.vm.blacksmith.sh
    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.

​
Pricing

There is no additional cost for using this feature. For all other pricing, please visit our pricing page.

​
FAQ

SSH access is opt-in and must be enabled by a GitHub organization admin:
  1. Navigate to the Settings > Features page
  2. Toggle “SSH Access” to enable it for your organization
  3. Organization members can now SSH into jobs they trigger
Only GitHub organization admins can toggle this setting.
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.
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.
Verify that:
  • SSH access is enabled for your organization (check with your GitHub org admin)
  • Your SSH key is properly added to your GitHub account
  • You’re a member of the GitHub organization
  • You’re the person who triggered the job (only the job sender can SSH in)
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!
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.
Let us know by opening a support ticket.