How to Deploy to a VPS Over SSH With Bitbucket Pipelines

Bitbucket injects the repository SSH key into the step, so an ssh user@host runs your deploy script on the server with no key handling needed.

Generate an SSH key pair in Repository settings (SSH keys), add the public key to the server, and add the host fingerprint as a known host. The private key is then available to every step automatically.

Steps

• In Repository settings to SSH keys, generate a key and add the host as a known host.
• Add the public key to ~/.ssh/authorized_keys on the server.
• Run ssh user@host to pull and restart the app remotely.
• Keep the remote deploy idempotent (git pull, build, restart service).

Pipeline

image: atlassian/default-image:4
pipelines:
  branches:
    main:
      - step:
          name: Deploy over SSH
          deployment: production
          script:
            - >
              ssh -o StrictHostKeyChecking=no $DEPLOY_USER@$DEPLOY_HOST
              "cd /var/www/app && git fetch --all && git reset --hard origin/main && npm ci --omit=dev && pm2 reload app"

Gotchas

• Add the server as a known host in Repository settings so the connection is not blocked.
• The repository SSH key is workspace-scoped; rotate it if a collaborator leaves.
• Prefer pipe: atlassian/ssh-run if you want a curated SSH wrapper instead of raw ssh.

Related guides