name: Deploy (SCP) # Reusable deploy workflow, invoked by continuous_integration.yaml (U5) for both the automatic # test deploy and the opt-in production deploy. One workflow, one input contract, so a second # transport (e.g. FTPS for a future shared-hosting target) can be added later as an alternative # without restructuring this workflow or its callers (FR-02, D-02, NFR-09). on: workflow_call: inputs: artifact_name: description: 'Build artifact to download and deploy' required: true type: string environment: description: 'Environment label, used in log output and step naming' required: true type: string deploy_path: description: 'Release root on the target host for this environment' required: true type: string service_name: description: 'systemd --user unit to restart after switching releases' required: true type: string health_check_url: description: 'Public /health URL to verify after restart' required: true type: string run_db_backup: description: 'Take a database backup before deploying (production only)' required: false type: boolean default: false transport: description: 'Transport mechanism. Only "scp" is implemented today; reserved for FTPS later' required: false type: string default: scp jobs: deploy: runs-on: linux steps: # Runner-independent: only installs what is missing, and only uses sudo when not already root and sudo exists # (a container on the PC runner has neither sudo nor a need for it; the Pi runner may need it). # # Authentication: the Pi-Main host only allows password login from the Pi runner's address, so every runner other # than that one needs a key. If the secret PI_MAIN_SSH_KEY (private key of the deploy account) is set and works, # the wrappers `rssh` / `rscp` below use it (-i, IdentitiesOnly, BatchMode); otherwise they fall back to sshpass # with the password, which keeps working from the Pi runner. The key lives in a temp directory that is removed # at the end of the job; it is never printed. - name: Ensure ssh tooling and authentication env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} SSH_KEY: ${{ secrets.PI_MAIN_SSH_KEY }} IN_DEPLOY_PATH: ${{ inputs.deploy_path }} IN_SERVICE_NAME: ${{ inputs.service_name }} IN_HEALTH_URL: ${{ inputs.health_check_url }} run: | # Inputs are not secret: print them so an empty one is visible, and stop before anything touches the host. echo "Inputs: deploy_path='$IN_DEPLOY_PATH' service_name='$IN_SERVICE_NAME' health_check_url='$IN_HEALTH_URL'" for v in IN_DEPLOY_PATH IN_SERVICE_NAME IN_HEALTH_URL; do if [ -z "${!v}" ]; then echo "Input $v is empty; refusing to deploy."; exit 1; fi done SUDO="" if [ "$(id -u)" != "0" ] && command -v sudo >/dev/null 2>&1; then SUDO="sudo"; fi if ! command -v sshpass >/dev/null 2>&1 || ! command -v ssh >/dev/null 2>&1 || ! command -v scp >/dev/null 2>&1; then $SUDO apt-get update && $SUDO apt-get install -y sshpass openssh-client fi D=$(mktemp -d) mkdir -p "$D/bin" echo "DEPLOY_TMP=$D" >> "$GITHUB_ENV" echo "$D/bin" >> "$GITHUB_PATH" if [ -n "$SSH_KEY" ]; then printf '%s\n' "$SSH_KEY" > "$D/key" chmod 600 "$D/key" if ssh -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=no -o ConnectTimeout=15 \ -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" true; then touch "$D/key_ok" echo "Authentication: deploy key" else echo "Deploy key rejected or host unreachable with it; falling back to password" fi else echo "No deploy key set; using password" fi cat > "$D/bin/rssh" <<'WRAP' #!/bin/sh D="$(dirname "$0")/.." if [ -f "$D/key_ok" ]; then exec ssh -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" "$@" fi exec sshpass -p "$SSH_PASS" ssh -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" "$@" WRAP cat > "$D/bin/rscp" <<'WRAP' #!/bin/sh D="$(dirname "$0")/.." if [ -f "$D/key_ok" ]; then exec scp -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=no -P "$SSH_PORT" "$@" fi exec sshpass -p "$SSH_PASS" scp -o StrictHostKeyChecking=no -P "$SSH_PORT" "$@" WRAP chmod +x "$D/bin/rssh" "$D/bin/rscp" - name: Compute release timestamp id: release run: echo "timestamp=$(date -u +%Y%m%d%H%M%S)" >> "$GITHUB_OUTPUT" - name: Download build artifact uses: actions/download-artifact@v3 with: name: ${{ inputs.artifact_name }} path: ${{ inputs.artifact_name }} # Production-only database backup, taken before anything on the host changes (FR-20, D-26). # The backup script itself lives on the host (created once during Operations host setup) and # is only invoked here — no database connection string or credential is ever known to this # workflow, keeping D-16 ("runtime secrets live in host environment variables") intact. # Gitea Actions does not resolve `${{ inputs.* }}` inside a step's `name:` (unlike inside # `run:`, where it works fine — see the echo below) — kept static rather than showing the # literal, unresolved `${{ inputs.environment }}` text in the log. - name: Back up database if: ${{ inputs.run_db_backup }} env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | echo "Environment: ${{ inputs.environment }}" rssh \ "bash ~/scripts/backup-slpsoftware-db.sh ${{ inputs.environment }}" # Uploads the published output to a fresh, timestamped release directory rather than # overwriting the live one (FR-06, D-27) — the atomic switch happens in a later step, once # this upload and the website-symlink step below have both succeeded. # # Plain shell step rather than a container SCP action: container-based actions fail on this # runner with "failed to attach to container: unable to upgrade to tcp, received 409", a known # limitation of Podman's Docker-compatible API for the attach/log-streaming that container # actions rely on (D-05). A plain scp command needs no nested container. # Same Gitea Actions limitation as the step above — static name, value logged via echo instead. - name: Upload release env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | echo "Environment: ${{ inputs.environment }}, transport: ${{ inputs.transport }}" RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "mkdir -p $RELEASE_DIR" rscp \ -r ${{ inputs.artifact_name }}/* \ "$SSH_USER@$SSH_HOST:$RELEASE_DIR/" # The customer's public website (wwwroot/web) must survive every CMS deploy (FR-08, ASM-01). # It lives outside the swapped release directory in a persistent shared/ folder, and is # symlinked into each new release. mkdir -p is idempotent, so this is also correct on the very # first-ever deploy, before any website workspace has published anything there (U1 already # tolerates a missing wwwroot/web at startup). The publish output's own wwwroot/web (empty, or # containing only the placeholder page) is removed before the symlink is created, so it never # shadows the persistent content. `mkdir -p $RELEASE_DIR/wwwroot` guards against `ln -s` failing # with "No such file or directory": dotnet publish only emits a wwwroot/ folder at all when the # source project has one with actual content, so a release built before any frontend content # exists can land with no wwwroot/ directory whatsoever, not merely an empty wwwroot/web/. - name: Link persistent website content env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "mkdir -p ${{ inputs.deploy_path }}/shared/wwwroot-web && \ mkdir -p $RELEASE_DIR/wwwroot && \ rm -rf $RELEASE_DIR/wwwroot/web && \ ln -s ../../../shared/wwwroot-web $RELEASE_DIR/wwwroot/web" # Optional plugin modules (future modular support): a compiled SlpModularCms.Modules.*.dll # dropped into shared/modules survives every release, the same persistence pattern as # shared/wwwroot-web above — except there's no cross-account permission dance here, since # shared/modules lives entirely under gitea-workflow's own tree (unlike wwwroot-web, which # reaches into webadmin's). ModuleOrchestrator.DiscoverModules() already scans its own base # directory on disk for matching assemblies at startup (SlpModularCms.Core/Hosting/ # ModuleOrchestrator.cs) and loads whatever it finds via reflection — no code change needed, # only somewhere for the DLL to still be after the next deploy replaces releases/{timestamp}. # `ls ... 2>/dev/null` piped to a `while read` (rather than a bare glob loop) keeps this # POSIX-sh safe and correct when shared/modules is empty, which is the common case today. - name: Link persistent modules env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "mkdir -p ${{ inputs.deploy_path }}/shared/modules && \ ls ${{ inputs.deploy_path }}/shared/modules/*.dll 2>/dev/null | while read -r f; do \ name=\$(basename \"\$f\"); \ ln -sf \"../../shared/modules/\$name\" \"$RELEASE_DIR/\$name\"; \ done" # Atomic release switch (FR-06, D-27): `ln -sfn` replaces the `current` symlink target in a # single filesystem operation, so there is no moment where `current` points at a half-written # directory. The process is then restarted so it picks up the new assemblies — a running .NET # process holds on to the ones it already loaded. - name: Switch current release and restart service env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "ln -sfn $RELEASE_DIR ${{ inputs.deploy_path }}/current && \ systemctl --user restart ${{ inputs.service_name }}" # Verifies the restart actually produced a healthy process before this run is allowed to # report success. Retries absorb ordinary process-startup time; a run that never turns healthy # fails the job without touching `current` or pruning (see below) — no automatic rollback. # A previous release is always still on disk to restore from manually (D-26). - name: Verify /health run: | for attempt in $(seq 1 10); do if curl -f -s -o /dev/null "${{ inputs.health_check_url }}"; then echo "Health check passed on attempt $attempt" exit 0 fi echo "Health check attempt $attempt failed, retrying..." sleep 3 done echo "Health check did not pass after 10 attempts" exit 1 # Retention: keep `current` plus exactly one previous release, so a manual rollback is always # a re-point-and-restart away without rebuilding. Only runs after a passing health check — # pruning after a failed check could leave the only other release as the sole survivor. - name: Prune old releases env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | rssh \ "cd ${{ inputs.deploy_path }}/releases && ls -1t | tail -n +3 | xargs -r rm -rf" - name: Remove deploy key if: always() run: rm -rf "${DEPLOY_TMP:-/nonexistent}"