A homemade CI/CD pipelinewith GitHub Actions

In the previous article on hosting a Next.js app on a VPS, I'd left the deployment pipeline as a rough sketch: four lines to say "it ships to production on its own when you push." That's the piece I want to open up here, because it's what separates a VPS you fuss over by hand from infrastructure you can forget about.

There's a stubborn myth that CI/CD is a big-company thing, with a dedicated DevOps team and six-figure tooling. Not true. The pipeline that deploys this portfolio fits in two YAML files, you can read it in five minutes, and it gives me back exactly the comfort I liked about Vercel: I push to master, I go grab a coffee, the app is live when I'm back. The one thing I gained along the way is knowing precisely what happens between the git push and the running container.

Four steps, in this order

Deployment is a chain. On every push to master, GitHub Actions runs lint, security scan, image build, and deploy. What matters is the needs: as long as a step fails, the following ones don't start. A critical vulnerability caught by the scan, and the image never gets built. At all.

jobs:
  lint:        # ESLint
    runs-on: ubuntu-latest
    # ...
  security:    # Trivy scan (reusable workflow)
    uses: ./.github/workflows/security.yml
  build-push:  # build the Docker image → push to GHCR
    needs: [lint, security]
    # ...
  deploy:      # SSH to the VPS → docker compose pull && up -d
    needs: [build-push]
    # ...

Lint first, because it's the cheapest step and there's no point building an image if ESLint is already screaming. The scan next, as a barrier. Then the build, which produces the Docker image and pushes it to GHCR, GitHub's container registry (private, in my case). And finally the deploy, which connects over SSH to the VPS, pulls the new image and restarts the container. Four links, each blocking the next. That's the whole secret.

The security scan is in the path, not in a review "for later"

This is the one I won't budge on. Dependency security, in a lot of projects, is a Dependabot opening PRs you read on Friday if there's time left (so, never). I've put it where it can't be ignored: on the deployment path. Trivy scans the repo's filesystem on every push, and if a critical or high CVE is hanging around, the pipeline fails before the build.

- name: Run Trivy vulnerability scanner
  uses: aquasecurity/trivy-action@master
  with:
    scan-type: "fs"
    scan-ref: "."
    severity: "CRITICAL,HIGH"
    ignore-unfixed: true   # don't block on what can't be fixed yet
    exit-code: "1"         # fail the run if a fix exists

The nuance that makes this livable is ignore-unfixed: true. Without that setting, the scan blocks you on vulnerabilities for which no fix exists upstream yet. You end up stuck, unable to deploy because of a flaw you can do strictly nothing about, and the temptation grows to turn the scan off "just for now." Bad idea, we know how that ends. With ignore-unfixed, the rule is clean: if a critical flaw has a fix available, you fix it before merging, full stop. If it doesn't, the pipeline lets you through and you keep an eye on it. Blocking on the unfixable isn't rigour, it's just self-sabotage.

In practice, that gives you mornings where the push fails with a Trivy report pointing at a version of Next to update. A yarn up next@<fixed-version>, a commit of the package.json and the lockfile, and you're off again. That friction, I want it. It's what keeps known vulnerabilities from sleeping six months in production.

From build to running container

The build step takes the image described by the Dockerfile (multi-stage, standalone output, I covered it in the previous article) and pushes it to GHCR tagged latest and sha-<commit>. The NEXT_PUBLIC_* variables get passed as build-args at this point, because they're inlined into the bundle at next build time. Everything that has to be visible browser-side is frozen here.

The deploy itself is almost boring, it's that simple, and that's exactly what you want from a deploy. An SSH action opens a session on the VPS and runs three commands there: a docker login to GHCR, a docker compose pull to fetch the fresh image, an up -d to swap the running container for the new one. No visible downtime, the old one keeps running until the new one is ready. None of these commands holds a single secret in plain text: the SSH key, the registry credentials, the target host, it all lives in GitHub secrets and resolves at runtime. The repo itself knows nothing. That's the ground rule, and it's non-negotiable: a committed secret is a burned secret, even in a private repo.

Validate on the PR, don't discover in production

Here's the first refinement I added after the fact, and one I'd put on any project from day one now. The deployment pipeline only fires on master. As long as I'm working on a branch, nothing builds, nothing ships. The catch is you don't want to merge blind either and find out the build breaks once it's on master, when the failure already kicks off the machine.

Hence a second workflow, pr-check, completely separate, that fires on Pull Requests. It runs lint, typecheck and build, but it deploys nothing.

on:
  pull_request:
    branches: ["master"]

The typecheck in particular is worth its weight in gold: ESLint catches style, but it's tsc that catches the real type errors, the ones that blow up a build. When a PR is green, I know the code compiles, the types hold, and the image builds. The merge becomes a formality instead of a gamble. Production is never again the first place I find out something doesn't pass.

Two details that prevent dumb damage

Editing a README should never trigger a full redeploy. Rebuilding a Docker image, pushing it, SSH, pull, restart, all that for a typo in a markdown file, is absurd. A paths-ignore on the trigger settles it.

on:
  push:
    branches: ["master"]
    paths-ignore:
      - "**.md"
      - "docs/**"
  workflow_dispatch:

I kept workflow_dispatch alongside, so I can force a deploy by hand from the GitHub UI if I do change something that only touches docs but still needs to ship. The service entrance, basically.

The other detail cost me a real scare before I put it in place. Picture two merges back to back, a minute apart. Two deployment pipelines start almost together, each builds its image, connects to the VPS out of order. That's exactly what happened to me: the two deploys collided, and the race was won by the image that was barely a second stale. The slower run's pull arrived last and overwrote production with the previous version. Green build on both sides, and yet the wrong version live. The kind of bug that makes you doubt your own sanity.

The countermeasure is three lines:

concurrency:
  group: deploy-production
  cancel-in-progress: true

One production deploy at a time. If a new one starts while another is still running, the old one is cancelled outright. The most recent commit always wins, by construction, and never again by chance. The race hasn't existed since.

None of this is wizardry. It's two YAML files, a few guardrails learned by banging into things a bit, and the same reflex as a managed platform: you push, it's live. The difference is that I know what's in the box, what it costs me, and that the day I want to change a link in the chain, it's there, readable, mine.

If you want to set up this kind of pipeline on your project, let's talk.