GitHub Actions Deploy to VPS: Build, Push to GHCR, SSH

  build-and-push:
    name: Build & push image
    needs: verify
    runs-on: ubuntu-latest
    # Same group as verify: one supersede cancels the whole build chain.
    concurrency:
      group: build-${{ github.ref }}
      cancel-in-progress: true
    permissions:
      contents: read
      packages: write
    outputs:
      image: ${{ steps.meta.outputs.image }}

needs makes this job wait for verify, and it shares verify's concurrency group, so one newer push cancels the whole build chain. It is the only job with packages: write. Its image output is how deploy learns which exact build to run.

  deploy:
    name: Deploy to VPS
    needs: build-and-push
    runs-on: ubuntu-latest
    # The one group that must NEVER cancel in progress. This step SSHes to the
    # VPS and runs `docker compose pull && up -d`; interrupting it can leave the
    # box between images. Concurrent deploys queue and run one at a time, which
    # is the original intent — it is only the build chain above that should be
    # throwing away superseded work.
    concurrency:
      group: deploy-vps
      cancel-in-progress: false
    permissions:
      contents: read
      packages: read

The other half of the split. deploy-vps never cancels a running deploy, so an SSH session is never cut off between pull and up. The job can read packages but not write them, which is all a server that only pulls needs.

      - name: Compute lowercase image ref
        id: meta
        run: |
          ref="$(echo "ghcr.io/${{ github.repository }}" | tr '[:upper:]' '[:lower:]')"
          echo "ref=${ref}" >> "$GITHUB_OUTPUT"
          echo "image=${ref}:${{ github.sha }}" >> "$GITHUB_OUTPUT"

      - uses: docker/setup-buildx-action@v3

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: |
            ${{ steps.meta.outputs.ref }}:latest
            ${{ steps.meta.outputs.ref }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

The image name comes from github.repository, lowercased with tr, so nothing about the registry path is typed by hand. The login uses the job's GITHUB_TOKEN, not a stored password. Two tags go up: latest for humans, and the commit SHA, which the image output carries to deploy.

      - name: Restore Next.js build cache
        uses: actions/cache@v4
        with:
          path: .next/cache
          # SHA in the key so every run writes a fresh entry; restore-keys then
          # falls back to the most recent cache for the same lockfile, and
          # finally to any cache at all, rather than starting cold.
          key: next-cache-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
          restore-keys: |
            next-cache-${{ hashFiles('package-lock.json') }}-
            next-cache-

An exact key hit would mean the cache is never saved again, so the key carries the SHA and is new on every run. restore-keys are prefixes: the newest cache for this lockfile wins, and any cache beats starting cold.

      # Best-effort, because it is an optimisation and the image is already
      # pushed by this point. It is meant to reuse every layer from the build
      # above, but on 2026-10-03 BuildKit had dropped them: this step re-ran
      # npm ci and the whole next build, then died with "EOF" exporting the
      # 572 MB cache. That failed the job, and `needs: build-and-push` then
      # skipped the deploy of an image that had built and pushed cleanly.
      - name: Extract Next.js build cache
        id: extract-next-cache
        continue-on-error: true
        uses: docker/build-push-action@v6
        with:
          context: .
          target: cache-export
          outputs: type=local,dest=/tmp/next-cache
          cache-from: type=gha

The return half of the round trip: build only the cache-export stage and write it to a local folder. The comment is the incident that made it best-effort. A later step checks steps.extract-next-cache.outcome, the result before continue-on-error is applied, and saves no cache when it failed.

            # Write runtime env from GitHub Secrets/Variables. Quoted heredoc so
            # shell does not expand anything in the (already-rendered) values.
            cat > .env <<'ENVEOF'
            GROQ_API_KEY=${{ secrets.GROQ_API_KEY }}
            RESEND_API_KEY=${{ secrets.RESEND_API_KEY }}
            CONTACT_FROM_EMAIL=${{ vars.CONTACT_FROM_EMAIL }}
            CONTACT_TO_EMAIL=${{ vars.CONTACT_TO_EMAIL }}
            IMAGE=${{ needs.build-and-push.outputs.image }}
            APP_PORT=${{ vars.APP_PORT || 3002 }}
            ENVEOF
            chmod 600 .env

            echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin

The only place the app's secrets appear. GitHub renders the expressions before the script runs, and the quoted 'ENVEOF' stops the shell from expanding a $ inside a value. IMAGE is the SHA-tagged reference from build-and-push. The token is piped to docker login, never passed as an argument.