GitHub Actions → Linux Deployment Template

A security-conscious reference for deploying a Node.js build from a GitHub-hosted runner to a Linux server over SSH—with immutable release directories, serialized production deployments, health verification, automatic rollback, and release retention.

Release flow

flowchart LR
    C[Commit] --> T[Test and build]
    T --> A[Immutable artifact]
    A --> E{Protected environment}
    E --> U[SSH upload]
    U --> R[Atomic symlink switch]
    R --> H{Health check}
    H -->|pass| K[Keep release]
    H -->|fail| B[Rollback]

Loading

What this demonstrates

• GitHub-hosted build and deploy jobs
• Minimal workflow permissions
• Protected production environment support
• Deployment concurrency that prevents overlapping releases
• Verified SSH host keys instead of disabled host checking
• Build-once artifact handoff between jobs
• Immutable SHA-addressed releases
• Atomic current symlink activation
• Post-deploy health checks and rollback
• systemd service hardening example
• Automatic retention of the newest releases

Use it

1. Copy examples/deploy.yml to your application as .github/workflows/deploy.yml.
2. Copy scripts/remote-deploy.sh into the application repository.
3. Adapt the install, migration, service, and readiness commands to your application.
4. Complete the one-time server setup.
5. Create a protected GitHub environment named production and configure its reviewers.

Set these environment secrets:

Secret	Example shape	Purpose
DEPLOY_TARGET	deploy@server.example	Non-root SSH destination
DEPLOY_SSH_KEY	private Ed25519 key	Dedicated deployment credential
DEPLOY_KNOWN_HOSTS	verified known-hosts line	Prevents machine-in-the-middle attacks

Never paste a real key, hostname, IP address, .env file, or cloud account identifier into the workflow.

Important assumptions

The example targets a single Linux host with systemd and Node.js already installed. It expects an application with a lockfile, tests, an optional build script, and a readiness endpoint. The deployment account needs write access only to the application release directory and narrowly scoped permission to restart the application service.

This is a reference implementation, not a drop-in guarantee. Threat-model it, test rollback in staging, verify backups, and tailor it to your infrastructure before production use.

Built as a public engineering reference by Manikandan Menon.