How to Deploy to a Server over SSH from Bitbucket Pipelines

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

To deploy through SSH from Bitbucket Pipelines, configure a deployment key, authorize its public half for a dedicated server user, verify the server’s host key, and pass the remote command as an argument to ssh. For example: ssh -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" 'cd /var/www/example && git pull --ff-only origin main'.

The old pattern ssh-add ~/.ssh/config is incorrect: ~/.ssh/config contains SSH client settings, not a private key. And ls | ssh ... pipes local output into SSH; it does not tell the server what deployment command to run. This guide shows the corrected setup, explains the common ssh_askpass failure, and covers both remote Git deployments and copying built files.

#	Preview	Product	Price
1		Modern OpenSSH In-Depth: The Complete Secure Shell Guide for SSH Server Configuration, Key...	$30.99	Buy on Amazon
2		Replacement Metal Key Hooks, Spring Lock for Key Cabinets & Board, 100 Pack	$86.93	Buy on Amazon

Choose what the pipeline should deploy

SSH is the connection method, not a deployment strategy. Decide whether the pipeline will ask the server to update a Git checkout or transfer a build artifact.

• Remote Git update: The server already has the application repository. The pipeline connects and runs a deployment command there. This is simple, but the server needs its own access to the repository.
• SCP or rsync: The pipeline builds the application and copies the resulting files to the server. The server does not need repository credentials, and CI deploys the artifact it tested.
• Release-based artifact deployment: The pipeline uploads files to a new release directory, then a remote command switches the live symlink or restarts the service. This takes more setup but makes validation and rollback easier.

For a small application with a deliberately maintained server-side checkout, remote Git can be adequate. For production, artifact deployment is often a better fit when you want the production server to run exactly what CI built.

#1 Best Overall

Modern OpenSSH In-Depth: The Complete Secure Shell Guide for SSH Server Configuration, Key Management, Tunneling, SFTP File Transfer, and DevOps Automation.

$30.99

Buy on Amazon

Configure SSH access in Bitbucket Cloud

Repository-level Pipelines SSH key

In Bitbucket Cloud, open the repository and go to Repository settings → Pipelines → SSH keys. Configure the Pipelines SSH key, then install its public key in the destination user’s ~/.ssh/authorized_keys on the server. The repository-level key is available as the default identity in the build environment; Bitbucket does not automatically authorize it on your server. See Atlassian’s Pipelines SSH key setup guide.

For multiple destinations or identities, use a dedicated key per deployment target and store a base64-encoded private key in a secured repository or deployment variable. Decode it to a temporary file, set restrictive permissions, and select it with ssh -i. Do not commit private keys or use a developer’s personal key. Secured variables are masked in logs, but repository write access is sensitive because pipeline code can use available variables. See Atlassian’s guidance on multiple SSH keys and variables and secrets.

Dedicated deployment key and user

Use a deployment-only identity, preferably without a passphrase when the pipeline must use it noninteractively. A passphrase-free key is not a reason to use a broadly privileged credential: restrict the key, limit the server user’s permissions, and rotate or revoke the key when needed. A more advanced setup can unlock a protected key noninteractively through an agent or secret-management system, but that is additional infrastructure.

On a Linux server, an administrator can create a non-root account and its SSH directory, for example:

sudo adduser --disabled-password --gecos "" deploy
sudo install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
sudo install -d -o deploy -g deploy /var/www/example

Add the pipeline’s public key to /home/deploy/.ssh/authorized_keys and set ownership and permissions:

sudo chown deploy:deploy /home/deploy/.ssh/authorized_keys
sudo chmod 600 /home/deploy/.ssh/authorized_keys

Give the account only the access required to deploy. If it must restart a service, prefer a narrowly scoped administrative rule over unrestricted sudo. Where practical, restrict the authorized key with SSH options such as restrict and disable forwarding; a forced command can constrain it further if the server-side deployment wrapper is designed for that purpose.

Verify the server’s host key

The client key proves the pipeline’s identity to the server. Host-key verification works in the other direction: it helps ensure the pipeline is connecting to the intended server. Do not solve host-key errors by disabling verification.

In the repository’s SSH key settings, add the server under the known-hosts facility and verify its displayed fingerprint through a trusted channel before saving it. The exact Bitbucket navigation can change; consult the current Atlassian SSH setup instructions.

Alternatively, commit a reviewed known_hosts file and copy it into the build user’s SSH directory. ssh-keyscan can collect a host key, but it does not prove the key belongs to the intended server. Generate the entry, verify its fingerprint out of band, and only then trust it:

ssh-keyscan -t ed25519,rsa example.com > my_known_hosts

Do not run ssh-keyscan during every build and blindly trust whatever it returns. That would remove the protection host-key verification is meant to provide.

Test the connection before deploying

Set SSH_USER, SSH_HOST, and SSH_PORT as repository or deployment variables. Use deployment-scoped variables for environment-specific values where appropriate. Add a deployment environment to the step when you want it associated with that Bitbucket deployment environment.

With a repository-level key and known host configured, a minimal pipeline can test authentication and connectivity. This example assumes the selected Linux image has an SSH client installed:

image: atlassian/default-image:3

pipelines:
  branches:
    main:
      - step:
          name: Test SSH connection
          deployment: staging
          script:
            - test -n "$SSH_USER"
            - test -n "$SSH_HOST"
            - test -n "$SSH_PORT"
            - ssh -o BatchMode=yes -o ConnectTimeout=15 -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" 'hostname'

BatchMode=yes stops SSH from waiting for a password or passphrase prompt. ConnectTimeout makes a network failure surface promptly. A successful hostname test confirms that SSH connected and ran a remote command; it does not confirm that the user can write the application files or restart a service.

Run a remote Git deployment

To update a server-side checkout, pass the command to run as the final argument to ssh. For example:

ssh -o BatchMode=yes 
  -o ConnectTimeout=15 
  -p "$SSH_PORT" 
  "$SSH_USER@$SSH_HOST" 
  'cd /var/www/example && git pull --ff-only origin main'

The conventional custom-port syntax is ssh -p 4000 [email protected] 'command'; omit -p for the default port. Keep the remote command in single quotes when it should be interpreted on the server. With double quotes, variables may expand in the pipeline container before SSH sends the command. For complex logic, a server-side script is easier to review and less error-prone than a long quoted command.

Rank #2

Replacement Metal Key Hooks, Spring Lock for Key Cabinets & Board, 100 Pack

• SPRING LOCK MECHANISM: Each hook is equipped with an advanced spring-loaded locking mechanism that delivers a strong and secure grip on keys. These metal key holder hooks prevent keys from slipping off or falling, ensuring safe and reliable storage in key cabinets, racks, and organizer boards.
• HIGH QUALITY BUILD: Made from premium-grade, heavy-duty metal, these key organizer hooks are built for durability and daily use. The rust-resistant construction ensures long-lasting performance for key storage boards, cabinets, and wall-mounted key racks in residential, office, or industrial environments.
• EASY INSTALLATION: These replacement key hooks feature a simple installation process. Just drill a small hole and fasten the hook with screws for a firm and secure fit. Perfect for DIY key storage projects, key cabinet repairs, or custom key panel installations.
• SECURITY FEATURES: Designed with a strong locking mechanism and reinforced metal body, these spring lock key hooks provide excellent security for key management systems. Ideal for homes, offices, hotels, garages, and automotive facilities that require dependable key rack accessories to prevent key loss or tampering.
• VERSATILE APPLICATION: Perfect for replacing old or damaged key hooks or for building custom key organizer boards. These universal key cabinet replacement hooks are suitable for key racks, wall panels, and storage systems, helping maintain an organized and accessible key management setup for any environment.

$86.93

Buy on Amazon

git pull --ff-only avoids creating a merge commit, but it can still fail if the remote checkout has diverged or contains local changes. For a deliberately disposable deployment checkout, a deterministic update can instead fetch the named branch and reset to it:

ssh -o BatchMode=yes -o ConnectTimeout=15 -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" 
  'cd /var/www/example && git fetch origin main && git reset --hard origin/main && ./deploy.sh'

Warning: git reset --hard discards local changes. Use it only if the checkout is disposable and configuration or persistent data is kept elsewhere. Before choosing either method, check the server’s remote and working tree; do not overwrite hand-edited production files by surprise.

The SSH key configured in Bitbucket authenticates the pipeline to the server. It does not give the server credentials to fetch a private Bitbucket repository. If the server runs git fetch or git pull, configure a separate server-to-Bitbucket credential, such as an approved repository access key or machine-user credential, and give it only the required access.

Use a server-side deployment script

Put complex or sensitive deployment logic in a reviewed script on the server, then invoke it over SSH. For example:

#!/usr/bin/env bash
set -Eeuo pipefail

app_dir=/var/www/example
branch=main

cd "$app_dir"
git fetch --prune origin "$branch"
git reset --hard "origin/$branch"

if [[ -x ./deploy.sh ]]; then
  ./deploy.sh
fi

The pipeline can call it with:

ssh -o BatchMode=yes -o ConnectTimeout=15 -p "$SSH_PORT" 
  "$SSH_USER@$SSH_HOST" '/usr/local/bin/deploy-example'

Ensure the script’s owner, permissions, Git credentials, executable paths, and service permissions are correct. Noninteractive SSH sessions may have a different PATH from an interactive login, so use absolute paths or set the required path explicitly.

Deploy built files with SCP

If CI builds the application, transfer its output rather than asking production to fetch or build source. A simple two-step example stores the build directory as an artifact, then uploads it with native SCP and switches a current symlink:

image: atlassian/default-image:3

pipelines:
  branches:
    main:
      - step:
          name: Build
          script:
            - ./ci/test.sh
            - ./ci/build.sh
          artifacts:
            - build/**

      - step:
          name: Deploy files
          deployment: production
          script:
            - scp -r -p -P "$SSH_PORT" build/. "$SSH_USER@$SSH_HOST:/var/www/example/releases/$BITBUCKET_BUILD_NUMBER/"
            - ssh -o BatchMode=yes -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" "ln -sfn /var/www/example/releases/$BITBUCKET_BUILD_NUMBER /var/www/example/current"

Adapt this to the application and server: create the release directory with the right ownership, verify the transfer, validate the release before making it live, and retain prior releases for rollback. A symlink switch alone is not a complete rollback plan, and database migrations or service restarts may need explicit sequencing.

For a standard SCP workflow with less custom shell scripting, Atlassian documents its SCP deployment pipe. Its example uses the atlassian/scp-deploy pipe and variables such as user, server, port, remote path, and local path. Check the documentation and pipe repository for the current version and supported variables rather than copying an old version number. A pipe simplifies file transfer; it does not by itself provide health checks, atomic releases, migrations, least-privilege permissions, or rollback.

Fixing ssh_askpass and other common errors

An ssh_askpass message usually means SSH tried to request a passphrase or password in a noninteractive job. In the original faulty command, ssh-add ~/.ssh/config also points at the wrong kind of file: ssh-add expects a private key, not client configuration. With Bitbucket’s repository-level default key, you generally do not need to run ssh-add at all. For a custom key, pass the private-key file with ssh -i, or add that key file to an agent if your setup requires one.

For a custom base64-encoded key stored as a secured variable, decode it to a temporary file with restrictive permissions and check that it is parseable without printing it:

mkdir -p "$HOME/.ssh"
chmod 700 "$HOME/.ssh"
printf '%s' "$DEPLOY_KEY_B64" | base64 --decode > "$BITBUCKET_CLONE_DIR/deploy_key"
chmod 600 "$BITBUCKET_CLONE_DIR/deploy_key"
ssh-keygen -y -f "$BITBUCKET_CLONE_DIR/deploy_key" > /dev/null
ssh -i "$BITBUCKET_CLONE_DIR/deploy_key" -o BatchMode=yes -p "$SSH_PORT" 
  "$SSH_USER@$SSH_HOST" 'hostname'
rm -f "$BITBUCKET_CLONE_DIR/deploy_key"

The key-parse check confirms that the private-key file can be read; it does not prove the server accepts it. Never print the private key or put it directly in the YAML.

Safe diagnostics can show the runtime context without exposing secrets:

whoami
pwd
ls -la "$HOME/.ssh"
ssh -V
ssh-add -l || true

Do not dump environment variables or private-key contents into the log.

When plain SSH deployment is not the right fit

Bitbucket Cloud Pipelines works well for a straightforward reachable server and a small number of deployment steps. If the target is only reachable inside a private network, a Linux self-hosted runner inside that network may be appropriate; it shifts responsibility to you to patch and secure the runner and its workspace. See Atlassian’s Linux Shell runner guidance.

If releases require approvals, coordinated multi-server rollout, health checks, audit history, or reliable rollbacks, a deployment platform may be worth evaluating instead of expanding a fragile SSH script. The Atlassian SCP pipe is an option for simple copying, while a managed deployment service is an operational alternative—not a prerequisite for using SSH. Choose based on network access, release controls, credential handling, and who will maintain the deployment system.

Quick Recap

Bestseller No. 1

Modern OpenSSH In-Depth: The Complete Secure Shell Guide for SSH Server Configuration, Key Management, Tunneling, SFTP File Transfer, and DevOps Automation.

$30.99

Bestseller No. 2

Replacement Metal Key Hooks, Spring Lock for Key Cabinets & Board, 100 Pack

$86.93

Deployment checklist

• Use a dedicated deployment key and server account; never commit the private key.
• Install the public key for the correct remote user and verify permissions.
• Verify the server host key through Bitbucket’s known-hosts setup or a reviewed file.
• Set the correct host, port, user, and remote path; test with a harmless command such as hostname.
• Use BatchMode=yes so the build fails rather than waiting for an interactive prompt.
• For remote Git, configure the server’s separate repository credential and understand the effect of any hard reset.
• For artifacts, upload to a release location, verify it, and plan service activation and rollback.
• Deploy to staging first and confirm the running application reports the expected commit or release.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.