Observability
SSH Access
Fastest way to debug running jobs and inspect VM state
Overview
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.Basics
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 theSetup runner step:
Simplify connections with SSH config
Add this to your~/.ssh/config file to streamline connections:
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
How do I keep a job running for debugging?
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:
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'?
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'?
Why am I getting 'Permission denied'?
Verify that:
- Your SSH key is properly added to your GitHub account
- Your SSH key is configured correctly for GitHub
- You’re the person who triggered the job (only the job sender can SSH in)
Can multiple people SSH into the same runner?
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?
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.
How can I get help with SSH access?
How can I get help with SSH access?
Let us know by opening a support ticket.