How to Make a Github Action That Exposes SSH Server
In the first post, I explained how to use action-sshd-cloudflared, a GitHub Action that I wrote to easily SSH to a GitHub workflow container and debug it efficiently. I gave a precise explanation of what the client commands do, and I compared it to similar alternatives.
In this post, we’ll go through the details of the server (the code that runs inside the GitHub workflow). We’ll see how to make a simple GitHub Action that runs a shell script (or anything executable), a couple useful environment variables, and most importantly, the recipe to run a SSH server there and expose it over the internet despite the container not being publicly addressable.
Making the simplest GitHub Action possible
All we need to turn a simple GitHub repository into a GitHub Action is to add a valid
action.yml at the top level.
name: Debug via SSHdescription: Setup a SSH server with a tunnel to access it to debug your action via SSH.
- run: $GITHUB_ACTION_PATH/setup-ssh
Unlike in a normal workflow YAML, the
run command must also include an explicit shell. We can use any of the GitHub Actions environment variables directly in there, which is convenient because we have
GITHUB_ACTION_PATH, the path to our action repository (by default the working directory is the one containing the user’s code, not our action code).
From there, the
[setup-ssh script](https://github.com/valeriangalliat/action-sshd-cloudflared/blob/master/setup-ssh) can be broken down in 9 simple steps:
- Download the latest
- Fetch the public SSH keys of the GitHub user who triggered the workflow to a
- If there was no SSH key, set a password for the
runneruser so that there’s alternative way to connect.
- Generate a server key.
- Create the
- Start a tmux session.
cloudflaredto expose the
sshdport on the internet.
- Output the client instructions.
- Wait for the tmux session to end and stop everything.
We start simple and easy.
curl --location --silent --output cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
chmod +x cloudflared
Fetch the actor keys
In GitHub Actions, the user who triggers the workflow is called an “actor”. Their username is set in the
GITHUB_ACTOR environment variable.
As you may know, you configured a number of SSH keys on GitHub to be able to push to repositories over SSH. Those keys are public knowledge, and we can fetch them via the public GitHub API, which is convenient here to automatically give the actor SSH access to that server.
curl -s "https://api.github.com/users/$GITHUB_ACTOR/keys" | jq -r '..key' > authorized_keys
The GitHub API response is in JSON, but we use a simple jq script to extract the raw key, one per line, to put it in a valid
Set a password
If there were no SSH keys for that user, we set a password as a fallback, so they still have a means to connect.
To test whether or not there was any SSH key, we use:
grep -q . authorized_keys
grepquiet (we don’t need to display the output),
.is the regular expression to match (any character), and
authorized_keysis the file we use as input.
If there’s any character in that file,
grep will exit with 0 (success). Otherwise with a nonzero code, which means nothing was matched.
We can conveniently use it in an
if grep -q . authorized_keys; then
echo "Configured SSH key(s) for user: $GITHUB_ACTOR"
echo "No SSH key found for user: $GITHUB_ACTOR"
echo "Setting SSH password..."
It’s in that
else branch that we generate and set the password. To generate it, we fetch 16 characters from
password=$(base64 < /dev/urandom | tr -cd '[:alnum:]' | head -c16)
base64 < /dev/urandomencodes as Base64 the stream of random bytes from
/dev/urandom. The stream is infinite but the pipeline is “lazy”.
tr -cd '[:alnum:]'keeps only alphanumeric characters.
head -c16keeps only the first 16 characters (or should I say bytes to be accurate) and terminates the stream as soon as it has them.
This gives us a password that we can set for the current user.
(echo "$password"; echo "$password") | sudo passwd "$USER"
We can’t use the
passwd command directly because it first prompts us for our own current password (which we don’t know), but we have
root access in this VM through
root doesn’t need confirmation to change anyone’s password.
We echo the password twice because
passwd typically asks to input the password first, then a second time for confirmation.
Generate a server key
ssh-keygen is a cool utility to generate SSH keys. It defaults to a RSA key which is fine with me.
qmakes it quiet (we don’t need the logs).
findicates the output file to write the key to (the public key will be in a file with a
N ''is to set an empty passphrase (otherwise
ssh-keygenwill prompt to set a passphrase).
ssh-keygen -q -f ssh_host_rsa_key -N ''
We copy it from a template file, where we just replace the
$USER symbols by the corresponding environment variable.
sed "s,\$PWD,$PWD,;s,\$USER,$USER," sshd_config.template > sshd_config
First we set the port to 2222, and we define the host key and process ID file. We could have written
PidFile none to prevent the default of
/run/sshd.pid, because we don’t actually use it, but it doesn’t hurt.
We enable PAM (pluggable authentication module). Not going in details with this, but keep in mind it’s required for this to work at least on Debian-based systems.
This enables interactive password authentication. They’re actually enabled by default so we could leave them out.
We only allow the Unix user who the workflow is running as, and we allow the SSH keys we fetched earlier in
authorized_keys. Remember that we replace those
$PWD symbols with a
sed command before starting the server, you can’t actually use variables in here otherwise.
ForceCommand tmux attach
Finally we force the
tmux attach command to run upon login. This makes sure the user is connecting to the tmux session we’ll start in the following steps, and it’s important because we monitor the status of this session to determine when to stop the server.
/usr/sbin/sshd -f sshd_config -D &
- We need to start it with an absolute path (it is required when starting an ad hoc SSH server like this).
flets us specify the configuration file to use.
Dstarts it as foreground (by default it starts as a daemon).
&makes it a background process in this script so that we can fetch its process ID with
$!right after, and kill it at the end.
We could avoid
& altogether by using the
sshd.pid file that we configured in
PidFile to retrieve the process ID instead. Whatever works.
Start a tmux session
(cd "$GITHUB_WORKSPACE" && tmux new-session -d -s debug)
We start a subshell (the parens around the command), so that
cd only affects the subshell and not our top-level environment.
We effectively change the current directory to the main workflow directory, defined in
GITHUB_WORKSPACE, and start a tmux session.
-d disables the default behaviour of attaching the session to the current terminal, and
-s allows us to give it a name.
./cloudflared tunnel --no-autoupdate --url tcp://localhost:2222 &
We run the
cloudflared binary that we downloaded to the current directory earlier. This command allows us to start a tunnel forwarding to port 2222, where our SSH server is listening.
And again, we terminate with
& to start it as a background process so that we can keep running commands and kill it at the end.
But there’s a few more things we need to add to this command:
./cloudflared tunnel ... 2>&1 | tee cloudflared.log | sed -u 's/^/cloudflared: /' &
stdout, so that we can
teewill write the input to the given file, but also keep outputting it to
stdoutat the same time.
- This is great because we can now use a simple
sedcommand to prefix it with
cloudflared:(so that the logs have some context).
This log file is useful for us to retrieve the relay URL that
cloudflared will output, which we do right after:
url=$(head -1 <(tail -f cloudflared.log | grep --line-buffered -o 'https://.*\.trycloudflare.com'))
tail -f cloudflared.logfollows the file, meaning that it keeps watching for new lines indefinitely, and outputs them as they come.
grepcommand has a simple regex to identify the relay URL.
-line-bufferedis important here because we want to work lazily and exit as soon as we find a match. If
grepwas buffering more than one line of data, this could just hang forever.
owill print only the text matched by the regex instead of the whole matching line.
- We put all of that in a subshell that we use as input to the
headcommand with the
head -1will exit the whole pipeline after one line is outputted, allowing us to continue running the script.
Note: We can’t put
head -1 at the end of the pipeline even though that would seem intuitive, because it would take
grep to try to write to the
head input after it was closed to notice that the pipe was broken, and then it would take another line output from
tail to notice that
In practice this just means this would hang indefinitely because
cloudflared doesn’t output the relay host twice.
See more details here.
Output the client instructions
We already have the
url variable as well as an optional
With that, all we need is the SSH server public key to include it as part of the connection command that the user will paste.
public_key=$(cut -d' ' -f1,2 < ssh_host_rsa_key.pub)
Thanks to the
cut command, we split the single line in the given file by space, and output only fields 1 and 2. This file normally has 3 fields: the key type, the actual key, and a comment. We don’t need the comment.
We can then display those variables in a friendly and convenient way to the user. I already detailed that in the first part focusing on the client side, check it out if you didn’t already!
Watch for session end
tmux wait-for channel
This commands waits for a channel named
channel to be “woken up” by a matching
tmux wait-for -S channel.
We don’t actually ever run this last command, and we don’t really care about the channel either, but the effect this will have if we never “wake up” the channel is that it will hang until the tmux session itself is over.
That’s exactly what we need: when the user is done debugging, they’ll typically end the tmux session, and this is our way to know we can tear down the servers:
And just like that, you know everything about action-sshd-cloudflared!
This script is simple enough to be explained in depth in a blog post, and builds on top of rock solid programs like
cloudflared and tmux.
Thanks to Cloudflare Tunnel guest mode, we don’t even need an API key or token to set up the relay, and because GitHub already exposes the actor public SSH keys, we can preconfigure them so that everything just works out of the box.
I hope GitHub introduces a SSH feature natively at some point, that would make actions like this obsolete. In the meantime, I hope this helps you debug your GitHub workflows!