Example: Debug a job with SSH

If your it's included within your actuated plan, then you can get a shell into any self-hosted runner - including GitHub's own hosted runners.

Certified for:

• x86_64
• arm64

Use a private repository if you're not using actuated yet

GitHub recommends using a private repository with self-hosted runners because changes can be left over from a previous run, even when using Actions Runtime Controller. Actuated uses an ephemeral VM with an immutable image, so can be used on both public and private repos. Learn why in the FAQ.

Try out the action on your agent

You'll need to add the id_token: write permission to your workflow to use this action. It allows the action to authenticate with the SSH gateway using an GitHub Actions OIDC token.

Create a .github/workflows/workflow.yaml file

name: connect

on:
  push:
    branches:
      - master
      - main
  workflow_dispatch:

permissions:
  id-token: write
  contents: read
  actions: read

jobs:
  connect:
    name: connect
    runs-on: actuated
    steps:
    - uses: self-actuated/connect-ssh@master

Next, trigger a build via the workflow_dispatch event or a git push to the master branch.

Open https://$SSH_GATEWAY/list in your browser and look for your session, you can log in using the SSH command outputted for you.

Alternatively, you can view your own SSH sessions from the actuated dashboard.

Whenever you have a build that you just can't figure out - or if you want to explore the runner and tune it up to your needs, then you can simply add - uses: self-actuated/connect-ssh@master where you want to pause the build.

To release the session run unblock or sudo reboot from the SSH session.

Watch a demo: