OpenClaw Gateway on Linux VPS in 2026: GitLab CI/CD Auto-Deploy vs Pure SSH Manual Update — Decision Matrix and Pipeline Pitfalls FAQ

Once an OpenClaw Gateway has lived on a small Linux VPS for a quarter, you stop arguing about Docker and start arguing about who pushes the next upgrade. In 2026 the realistic fork is GitLab CI/CD auto-deploy (merge requests, protected branches, runner-driven SSH) versus a pure SSH manual update (you in a terminal, openclaw update or docker compose pull, then health checks). Both ship; they fail differently. This piece is the GitLab-flavored sibling of our OpenClaw Gateway on Linux VPS in 2026: GitHub Actions CI/CD vs Manual Docker Deploy — Decision Matrix, Repro Steps, and FAQ, with the same production-onboarding baseline assumed.

Decision matrix: when GitLab CI/CD wins, when pure SSH wins

Read the table as a regret minimizer — “green” is not mandatory, it is the side you would rather be on when the relevant incident actually fires.

GitLab CI/CD: a minimal Gateway pipeline that does not lie

The smallest pipeline that earns its keep has three jobs: build (image with digest), deploy (SSH into the VPS via a protected job), and verify (loopback health probe). Tag it on protected branches, gate the deploy on a manual environment, and never let a feature branch reach prod.

# Stages: build → deploy → verify
stages: [build, deploy, verify]

build_image:
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  only: [main]

deploy_vps:
  stage: deploy
  environment: { name: production, url: https://gateway.example.com }
  when: manual           # human gate before prod
  before_script:
    - eval $(ssh-agent -s) && echo "$SSH_PRIVATE_KEY" | ssh-add -
    - mkdir -p ~/.ssh && ssh-keyscan $VPS_HOST >> ~/.ssh/known_hosts
  script:
    - ssh deploy@$VPS_HOST "cd /srv/openclaw &&
        export IMAGE=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA &&
        docker compose pull && docker compose up -d"

verify_health:
  stage: verify
  script:
    - ssh deploy@$VPS_HOST "curl -fsS http://127.0.0.1:<health-port>/health"

• Protected variables — store SSH_PRIVATE_KEY, VPS_HOST, registry token as masked + protected; restrict to protected branches/tags only.
• Pin by digest, not by tag — promote $CI_COMMIT_SHA (or the resolved sha256:) so re-runs are deterministic; :latest in production is how Friday afternoons go bad.
• Manual prod gate — the production environment job stays when: manual; pipelines are auditable, but humans still pull the trigger.
• Runner separation — use a dedicated runner (or a tagged shared one) for deploy jobs; the build runner should not hold prod SSH keys.

Pure SSH manual update: a runbook, not a vibe

Manual deploy is fine — provided you treat it as a runbook, not muscle memory. The point is to make the next person (or future-you at 2 a.m.) able to repeat what you did.

1. Pre-flight — record the current image digest and config hash: docker compose images > ~/openclaw/state/$(date +%F).txt.
2. Snapshot state — tar the persistent volumes (tokens, sessions, sqlite). Without this, “rollback” is wishful thinking.
3. Apply — openclaw update for managed installs, or docker compose pull && docker compose up -d for compose-based ones.
4. Verify — loopback health, then run openclaw doctor; if you proxy through nginx/Caddy, curl the public URL too.
5. Roll back if needed — docker compose down && IMAGE=<prev-digest> docker compose up -d; restore volumes only if the upgrade migrated state.

FAQ: pipeline pitfalls we keep seeing

The pipeline goes green but the Gateway is still on the old image?

Almost always a tag-vs-digest issue. Either the deploy job pulled :latest (cached on the host) or docker compose reused an existing container because nothing in compose.yml changed. Pin image: to the digest produced by the build job and add --force-recreate when in doubt.

SSH from the runner suddenly fails with “host key verification failed.”

The VPS was reinstalled or its SSH host key rotated. Refresh known_hosts via ssh-keyscan in before_script, and store the expected fingerprint as a CI variable so a silent host swap fails loudly instead of trusting whatever answers.

Where should secrets live — GitLab or the VPS?

Channel tokens and registry credentials belong in GitLab as masked + protected variables; long-lived state (session DBs, OAuth refresh tokens already issued to the Gateway) stays on the VPS volume. The pipeline should never need to read user-session data.

Can we keep manual SSH and still get an audit trail?

Yes — the practical hybrid is: GitLab builds and pushes the image (audited, reproducible), then a human SSHes in to docker compose pull the exact digest. You skip the deploy-job complexity but keep registry tags as your timeline.