English
Access for GitHub
The deploy job runs on a GitHub runner and must log in to your server. This chapter gives it exactly that access — a key of its own, the server's identity, and a protected place for both — and then reads the job that uses them.
Step 1. A deploy key
Why. The runner needs an SSH key. It should not be your key: that key also opens your other servers and repositories, and you could not revoke the runner's access without locking yourself out. A deploy key is a key pair made for one purpose. If it leaks, you delete one line on the server, and nothing else is affected.
Do. On your computer, in a folder outside the repository (for example your home folder), create the pair without a passphrase — the runner cannot type one:
powershell
ssh-keygen -t ed25519 -N "" -f chatex-deployThe command writes two files: chatex-deploy, the private key, which goes into a GitHub secret in Step 3 and nowhere else, and chatex-deploy.pub, the public key, which goes to the server.
On the server, allow the public key to log in. Paste the content of chatex-deploy.pub (one line that starts with ssh-ed25519) into this command:
bash
echo '<contents of chatex-deploy.pub>' >> /root/.ssh/authorized_keys>> appends the line; a single > would overwrite the file and remove your own key.
Check
From your computer, log in with the new key:
powershell
ssh -i chatex-deploy root@<droplet ip>You are logged in without a password. Type exit to leave.
Step 2. The host key
Why. SSH authenticates in both directions. The server proves its identity with its host key; on your computer, known_hosts remembered it at the first login (topic 23). A runner is a fresh machine every time and has never seen your server. If it accepted whatever key the address offers, an attacker who redirected the address — a hijacked DNS record, a hostile network — would receive the release and could feed fake answers to the deployment. So we give the runner the server's key in advance, and it refuses every other.
Do. On your computer, ask the server for its Ed25519 host key:
powershell
ssh-keyscan -t ed25519 <droplet ip>The output has a comment line on the error stream, # <droplet ip>:22 SSH-2.0-OpenSSH_10.2p1 Ubuntu-…, and one line of the form <droplet ip> ssh-ed25519 AAAAC3NzaC1lZDI1NTE5…. That line is the value of the secret SSH_KNOWN_HOSTS.
Compare before you trust
ssh-keyscan itself trusts the network. Compare its result with the key the server reports about itself, over the session you already trust:
bash
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pubThe fingerprint (SHA256:…) must match the one that ssh-keygen -lf shows for the scanned line, or the one in your known_hosts file. The deploy job prints both sides again in its log.
Step 3. The production environment
Why. The deploy job needs four secrets and one public value. GitHub keeps secrets encrypted, never shows them again after saving, and masks them in logs. An environment goes one step further: its secrets are available only to jobs that declare environment: production, and only after the environment's protection rules pass. The rule we want is a required reviewer: every deployment waits until you approve it.
Do. On GitHub, open Settings → Environments → New environment, name it production, and add these values (Table 24.1) under Environment secrets and Environment variables.
Table 24.1. Secrets and variables of the production environment
| Name | Kind | Value |
|---|---|---|
SSH_HOST | secret | the droplet's IP address |
SSH_USER | secret | root |
SSH_PRIVATE_KEY | secret | the contents of chatex-deploy (the private key), all lines including -----BEGIN and -----END |
SSH_KNOWN_HOSTS | secret | the output of ssh-keyscan -t ed25519 <droplet ip> |
PUBLIC_URL | variable | https://<your domain>, without a slash at the end |
Under Deployment protection rules on the same page, turn on Required reviewers, add yourself, and save the protection rules.
Delete the local file chatex-deploy now, or keep it in a password manager: GitHub has the only copy that is needed.
Environments and plans
GitHub's plans differ here. At the time of writing, environments, their secrets and required reviewers are available in public repositories on every plan. In a private repository, environments and their secrets need GitHub Pro (free for students with the GitHub Student Developer Pack), and required reviewers are not available at all on the Free, Pro and Team plans. The simplest way for this course is to make your repository public: it contains no secret — that is exactly what chatex.env.example and this chapter were designed for — and the ruleset of topic 22 is then enforced too. Check Managing environments for deployment for your plan. Without an approval rule the workflow still works; it simply deploys every merge without waiting.
Step 4. The deploy job
Why. Now the job of deploy.yml that we skipped in The deploy workflow can be read with all its parts in place.
yaml
deploy:
name: Deploy
needs: package
runs-on: ubuntu-latest
timeout-minutes: 15
environment:
name: production
url: ${{ vars.PUBLIC_URL }}
env:
SSH_HOST: ${{ secrets.SSH_HOST }}
SSH_USER: ${{ secrets.SSH_USER }}
RELEASE: ${{ github.sha }}
steps:
- uses: actions/download-artifact@v8
with:
name: chatex-release
path: releaseenvironment: name: productionbinds the job to the environment: GitHub pauses here until a reviewer approves, and only then gives the job the environment's secrets.urlshows the address of the site as a link on the run page.env:passes the host, the user and the commit hash to every step as environment variables. The steps use"$SSH_HOST"in the shell instead of expressions inside the commands — the safe pattern from topic 22.download-artifactfetches the release that the package job uploaded, intorelease/.
Setting up SSH
yaml
- name: Set up SSH
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
SSH_KNOWN_HOSTS: ${{ secrets.SSH_KNOWN_HOSTS }}
run: |
install -m 700 -d ~/.ssh
printf '%s\n' "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
host=$(printf '%s' "$SSH_HOST" | tr -d '[:space:]')
user=$(printf '%s' "$SSH_USER" | tr -d '[:space:]')
# ...
printf 'Host deploy-target\n HostName %s\n User %s\n IdentityFile ~/.ssh/deploy_key\n IdentitiesOnly yes\n StrictHostKeyChecking yes\n' \
"$host" "$user" > ~/.ssh/config- The private key is written to
~/.ssh/deploy_keywith the mode600; SSH refuses keys that others can read.tr -d '\r'removes Windows line endings that sneak in when a key is pasted from a Windows editor — a classic cause oferror in libcrypto. hostanduserare trimmed of spaces and line breaks, which a pasted secret often contains.- The
known_hostsfile (the lines elided above) is built fromSSH_KNOWN_HOSTSwithawk: comment and empty lines are skipped, and from every other line only the key type and the key are kept and pinned toSSH_HOST. So it does not matter whether the secret contains a host name, an IP, comments or Windows line endings. An empty result fails the step withSSH_KNOWN_HOSTS contains no host key lines. - Fingerprints of both sides are printed: the pinned keys, and what the server actually offers (
ssh-keyscan). Fingerprints are public, and a mismatch is then visible in the log at a glance. - The SSH configuration defines the alias
deploy-targetwith the host, the user and the key.IdentitiesOnly yesuses only this key;StrictHostKeyChecking yesrefuses any server whose key is not inknown_hosts, instead of asking.
In the log of a run the step prints, for example:
Pinned host keys:
SHA256:DE86BpW+JqcfKLcLqOlShgkKAsdWshOwqvqMPhPTlk4 (ED25519)
Keys the server offers:
SHA256:FmmRxq1IGX36rJosgWw43kDvGaw4wA3RsS5hkFXbCQE (RSA)
SHA256:boPTHa48CvkJEvzIT3OQJqcvid5s565DajU8yK56qbU (ECDSA)
SHA256:DE86BpW+JqcfKLcLqOlShgkKAsdWshOwqvqMPhPTlk4 (ED25519)The pinned Ed25519 fingerprint appears among the offered ones: the runner talks to the right server.
Upload, activation and smoke test
yaml
# Uploads go to incoming/; chatex-activate moves them into releases/.
- name: Upload release
run: rsync -rltz --delete --chmod=Du=rwx,Dgo=rx,Fu=rw,Fgo=r release/ "deploy-target:/opt/chatex/incoming/$RELEASE/"
- name: Activate release
run: |
# RELEASE is meant to expand on the runner.
# shellcheck disable=SC2029
ssh deploy-target sudo /usr/local/bin/chatex-activate "$RELEASE"
- name: Smoke test
env:
PUBLIC_URL: ${{ vars.PUBLIC_URL }}
run: curl --fail --silent --show-error --retry 10 --retry-delay 3 --retry-all-errors "$PUBLIC_URL/health"rsynccopies the release over SSH into/opt/chatex/incoming/<sha>/:-rrecursively,-lsymbolic links as links,-twith modification times,-zcompressed.--deleteremoves files in the target that are not in the release, so a repeated upload of the same commit is an exact copy.--chmodsets predictable permissions — foldersrwxr-xr-x, filesrw-r--r--— whatever the runner had; the activation script fixes owners and the execute bit ofefbundle. Uploading intoincoming/keeps a half-finished copy out ofreleases/.ssh deploy-target sudo /usr/local/bin/chatex-activate "$RELEASE"runs the script of the previous chapter on the server, by its full path.$RELEASEis expanded by the runner's shell before SSH sends the command, which is intended — that is what theshellcheckcomment says.sudochanges nothing forroot, but the same line works unchanged for a deploy user that may run only this command. The script's output appears in the job log, and its exit code decides the colour of the step.- The smoke test asks the public address, through DNS, TLS and Nginx, whether the site is healthy: up to ten retries three seconds apart, also on connection errors (
--retry-all-errors).--failturns an HTTP error into a failed step. It is the second health check: the script checked from inside the server, this one checks what users see.
Every step depends on the previous one: if the upload fails, nothing is activated; if the activation fails (and rolls back), the smoke test does not run and the job is red.
Check
The workflow has not run yet, so check the configuration: on GitHub, Settings → Environments → production lists four secrets, one variable and the required reviewer. Compare your workflows with the reference:
powershell
git diff --no-index .github/workflows/deploy.yml D:\Work\Chatex-Reference\.github\workflows\deploy.ymlThe command prints nothing.