English
The deploy workflow
Step 1. Continuous deployment
Why. A deployment by hand is a list of steps: build, copy, migrate, restart, check. Done once a month, every step is a chance for a mistake — a build from the wrong branch, a forgotten migration, a restart before the copy finished. Done by a workflow, the same steps run the same way every time, and deploying becomes cheap enough to do after every change. Small, frequent deployments are also safer: when something breaks, the cause is in the last few commits.
Chatex deploys every change of main. Strictly speaking it is continuous delivery: every change is built, tested and ready, and a person presses the button. The button is a required approval in GitHub (chapter Access for GitHub); remove it, and the same workflow does continuous deployment.
Two principles shape the workflow:
- Build once, deploy the same bytes. The release is built and packaged in one job and stored as an artifact; the deploy job only copies it. Nothing is compiled on the server, so the server needs no SDK, no Node.js and no source code.
- The server decides whether the release is good. After switching, the server checks
/healthand goes back to the previous release by itself if the answer is notHealthy(next chapter).
Step 2. The workflow file
Do. Create the second workflow next to ci.yml:
yaml
# Production deploy: CI, then package the API, the migration bundle and the web app,
# then (after approval on the "production" environment) copy them to the server and activate.
# Server setup and the required secrets are described in Docs/Deployment.md.
name: Deploy
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: production
cancel-in-progress: false
env:
DOTNET_NOLOGO: true
DOTNET_CLI_TELEMETRY_OPTOUT: true
jobs:
ci:
name: CI
uses: ./.github/workflows/ci.yml
package:
name: Package
needs: ci
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
with:
global-json-file: global.json
- name: Cache NuGet packages
uses: actions/cache@v6
with:
path: ~/.nuget/packages
key: nuget-${{ runner.os }}-${{ hashFiles('Directory.Packages.props', '**/*.csproj') }}
restore-keys: nuget-${{ runner.os }}-
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
cache-dependency-path: Source/Chatex.Web/package-lock.json
- name: Publish API
run: dotnet publish Source/Chatex.Api -c Release -r linux-x64 --self-contained false -o release/api
- name: Build migration bundle
run: |
dotnet tool restore
dotnet ef migrations bundle --project Source/Chatex.Data --configuration Release -r linux-x64 -o release/efbundle
- name: Build web app
working-directory: Source/Chatex.Web
run: |
npm ci
npm run build
cp -r dist/chatex/browser ../../release/web
- name: Add release metadata
run: |
echo "${{ github.sha }}" > release/REVISION
cp Deploy/activate-release.sh release/
- uses: actions/upload-artifact@v7
with:
name: chatex-release
path: release/
retention-days: 14
if-no-files-found: error
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: release
- 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:]')
# Keep only "<type> <key>" from each line of SSH_KNOWN_HOSTS and pin it to SSH_HOST,
# so comments, Windows line endings or a different host name in the secret don't matter.
printf '%s\n' "$SSH_KNOWN_HOSTS" | tr -d '\r' \
| awk -v host="$host" '!/^[[:space:]]*(#|$)/ {
for (i = 1; i < NF; i++) if ($i ~ /^(ssh-|ecdsa-|sk-)/) { print host, $i, $(i + 1); break }
}' > ~/.ssh/known_hosts
if [ ! -s ~/.ssh/known_hosts ]; then
echo "::error::SSH_KNOWN_HOSTS contains no host key lines"
exit 1
fi
# Fingerprints are public; print both sides so a mismatch is visible in the log.
echo "Pinned host keys:"
ssh-keygen -lf ~/.ssh/known_hosts | awk '{ print " " $2, $NF }'
echo "Keys the server offers:"
ssh-keyscan -T 10 "$host" 2>/dev/null | ssh-keygen -lf - | awk '{ print " " $2, $NF }'
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
# 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"The workflow has three jobs that run one after another, because each needs the previous one: ci → package → deploy. The rest of this chapter covers the first two; the deploy job follows in Access for GitHub, after the server part it talks to.
Step 3. Triggers and concurrency
yaml
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: production
cancel-in-progress: falsepushtomain— every merged pull request deploys. Together with the ruleset of topic 22, only checked code reachesmain.workflow_dispatchadds a Run workflow button on the Actions page, to deploy the currentmainagain without a new commit — for example after changing a secret.permissions: contents: read— the jobs need nothing but reading the repository. The rights to the server come from secrets, not from the token.concurrency: group: productionwithcancel-in-progress: false— at most one run of the group runs at a time; a newer run waits instead of cancelling the running one. Cancelling a deployment between "migrate" and "switch" would leave the server in a state nobody tested. (If several runs wait, GitHub keeps only the newest waiting one, which is what we want: it contains all the changes.)
Step 4. Reusing CI
yaml
ci:
name: CI
uses: ./.github/workflows/ci.ymlA job with uses: instead of runs-on: calls a reusable workflow — possible because ci.yml declares the event workflow_call (topic 22). Both jobs of CI run again on the commit of main, and the deployment continues only if both are green. Why check again what the pull request already checked? Because main after the merge is a new commit: two pull requests that were green on their own can break each other once both are merged. And the same file serves both workflows, so there is only one definition of "checked".
On the run page, the jobs appear as CI / Backend and CI / Frontend.
Step 5. The package job
Why. The server needs four things, and nothing else: the API ready to run, a way to apply the migrations without the SDK, the static files of the client, and a note which commit they come from. The package job produces them in a folder release/ and stores it as an artifact.
Do. The job, without its setup steps, which are the same as in CI:
yaml
package:
name: Package
needs: ci
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
# ...
- name: Publish API
run: dotnet publish Source/Chatex.Api -c Release -r linux-x64 --self-contained false -o release/api
- name: Build migration bundle
run: |
dotnet tool restore
dotnet ef migrations bundle --project Source/Chatex.Data --configuration Release -r linux-x64 -o release/efbundle
- name: Build web app
working-directory: Source/Chatex.Web
run: |
npm ci
npm run build
cp -r dist/chatex/browser ../../release/web
- name: Add release metadata
run: |
echo "${{ github.sha }}" > release/REVISION
cp Deploy/activate-release.sh release/
- uses: actions/upload-artifact@v7
with:
name: chatex-release
path: release/
retention-days: 14
if-no-files-found: errordotnet publish … -r linux-x64 --self-contained false -o release/api— the API with all its libraries, compiled in Release for 64-bit Linux, intorelease/api. Framework-dependent (--self-contained false): the .NET runtime is not included, because the server has it from the Ubuntu packageaspnetcore-runtime-10.0and receives its security updates from there. A self-contained publish would carry the whole runtime, tens of megabytes more, and would freeze its version until the next deployment.dotnet ef migrations bundle … -o release/efbundle— the migration bundle announced in topic 4: a single Linux executable that contains every migration ofChatex.Dataand applies the missing ones to the database given with--connection. The server needs neither the SDK nordotnet-efnor the source code.--configuration Release(spelled out: indotnet ef,-cmeans--context) builds the data project in Release.npm ci,npm run build,cp -r dist/chatex/browser ../../release/web— the production build of the client, the folder that Nginx serves ascurrent/web.REVISION— the full commit hash. The expression in double curly braces is replaced by GitHub before the shell runs; on the server,cat /opt/chatex/current/REVISIONtells you exactly which commit is live.cp Deploy/activate-release.sh release/— a copy of the activation script that belongs to this release, for reference. The server runs its installed copy in/usr/local/bin(next chapter); a change of the script in the repository must also be installed on the server by hand.upload-artifactstoresrelease/as the artifact chatex-release of the run for 14 days.if-no-files-found: errorfails the job if the folder is missing, instead of deploying nothing.
Why not build on the server?
Building on the server is the classic shortcut: git pull && dotnet publish && npm run build in an SSH session. It needs the SDK and Node.js on the production machine, gigabytes of build caches next to the live data, minutes of high CPU load while users are chatting, and it deploys whatever happens to compile there — not what CI tested. The artifact avoids all four problems.
Step 6. Building a release locally
Why. Before the workflow runs on GitHub, it is worth seeing the release once with your own eyes — and knowing how to build it is useful when GitHub is down (see "Deploying by hand" in Deployment and operations).
Do. From the repository root, run the commands of the package job:
powershell
dotnet publish Source/Chatex.Api -c Release -r linux-x64 --self-contained false -o release/apipowershell
dotnet tool restorepowershell
dotnet ef migrations bundle --project Source/Chatex.Data --configuration Release -r linux-x64 -o release/efbundleThe bundle step ends with Done. Migrations Bundle: …\release\efbundle.
Check
powershell
Get-ChildItem releaseThe folder contains api and the file efbundle (about 34 MB). release/api holds Chatex.Api.dll, the libraries and appsettings.Production.json — about 12 MB in total. The folder release/ is ignored by Git (.gitignore of topic 2 lists [Rr]elease/), so git status stays clean. Delete it when you have looked around:
powershell
Remove-Item -Recurse releaseCommit the workflow and push it to dev:
powershell
git add .githubpowershell
git commit -m "Add the deploy workflow"powershell
git pushNothing is deployed yet: the workflow runs on main, and the server is not ready to receive a release until the next two chapters are done.