Continuous deployment for WordPress with Bitbucket Pipelines means every push to your repository can automatically build, test, and deploy your site to a server, eliminating manual FTP or SSH uploads. You set up a pipeline file in your repo that defines the steps, and Bitbucket runs them on a cloud or self-hosted runner whenever you push to a branch. This article explains how it works, what you need, common pitfalls, and whether it’s the right choice for your WordPress workflow.
Why Use Bitbucket Pipelines for WordPress
WordPress sites are often managed by hand: edit files locally, upload via FTP, and hope nothing breaks. That approach is slow, error-prone, and hard to roll back. Continuous deployment (CD) automates the upload step so that every approved change goes live the same way every time. Bitbucket Pipelines is a built-in CI/CD service in Bitbucket Cloud, so you don’t need a separate tool like Jenkins or Travis. It reads a bitbucket-pipelines.yml file at the root of your repository and runs the steps you define in a fresh Docker container. For WordPress, the typical pipeline does three things: install dependencies (like Composer or npm), run tests or linting, and deploy files to your server via SSH or SFTP.
Prerequisites and Initial Setup
Before writing your pipeline, you need a few things in place:
- A Bitbucket repository containing your WordPress theme, plugin, or full site code.
- SSH access to your web server (shared hosting often supports it, but some cheap plans don’t).
- An SSH key pair – the private key stays in Bitbucket as a repository variable, the public key goes on your server’s
~/.ssh/authorized_keys. - An SSH host key fingerprint so Bitbucket can verify the server’s identity.
To add the private key and other secrets, go to Repository Settings → Repository variables. Common variables are SSH_PRIVATE_KEY, SSH_HOST, SSH_USER, and SSH_PORT (usually 22). Never hardcode secrets in the pipeline file – use variables, which are masked in logs.
Writing Your First Pipeline
The pipeline file is YAML. A minimal example that deploys a theme folder to a server looks like this:
image: atlassian/default-image:3
pipelines:
branches:
main:
- step:
name: Deploy theme
deployment: production
script:
- apt-get update && apt-get install -y rsync
- mkdir -p ~/.ssh
- echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
- chmod 600 ~/.ssh/id_rsa
- ssh-keyscan -H $SSH_HOST >> ~/.ssh/known_hosts
- rsync -avz --delete ./wp-content/themes/mytheme/ $SSH_USER@$SSH_HOST:/path/to/wp-content/themes/mytheme/
This runs on every push to main. It installs rsync, sets up the SSH key, and synchronizes the theme folder. The --delete flag removes files on the server that no longer exist locally – use it only if you are sure the local folder is the source of truth. For a plugin, change the paths accordingly.
Deploying the Whole Site vs. Just Code
There are two main strategies. The first is deploying only your custom code – themes, plugins, and mu-plugins – leaving the WordPress core and database untouched. This is safer because you never overwrite wp-config.php or uploads. The second is deploying an entire WordPress instance, including core, if you track it in the repository (for example, using Composer with johnpbloch/wordpress-core). That approach gives you reproducible builds but requires a build step to generate the full file tree. Most teams start with code-only deployment, then move to a Composer-managed full build if they need core updates to be part of the pipeline.
Handling Database and Uploads
Pipelines cannot directly deploy the database or the wp-content/uploads folder easily. The database is dynamic and changes constantly; syncing it via pipeline would overwrite live data. Instead, use a plugin like WP-CLI to run wp db export on the server after deployment, or ignore the database in the pipeline and manage it separately. For uploads, the standard practice is to exclude them from the repo and use a storage service like S3, or simply not sync them at all. If you must sync uploads, use rsync with --ignore-existing to avoid overwriting newer files, but be careful – this is a common source of data loss.
Common Problems and How to Avoid Them
Several issues trip up beginners:
- SSH key permissions – the private key must have
chmod 600, otherwise SSH refuses to use it. - Host key verification – use
ssh-keyscanto add the host to known_hosts, or setStrictHostKeyChecking=no(less secure but common in quick setups). - Path mismatches – absolute paths on the server are often different from local ones. Use a variable for the remote path and test with a dry run (
rsync -avz --dry-run). - File permissions – rsync preserves permissions by default; if your local files have wrong ownership, they will be wrong on the server. Use
--chmod=Du=rwx,Dgo=rx,Fu=rw,Fgo=rto set sane defaults. - Pipeline timeout – free Bitbucket pipelines have a 50-minute limit per step; large sites may exceed it. Split into multiple steps or use a self-hosted runner.
Another misconception is that deployment is instant. In reality, rsync can take minutes for large sites, and the pipeline queues during peak times. Plan for a few minutes of downtime if you replace files while the site is live – though WordPress usually handles it fine because PHP loads files per request.
Comparing with Other CI/CD Tools
Bitbucket Pipelines is not the only option. GitHub Actions and GitLab CI offer similar features. Bitbucket’s advantage is that it’s already integrated if you use Bitbucket for code hosting; you don’t need to connect a third-party service. It also has built-in deployments with environments (staging, production) and can restrict deployments to manual approval. GitHub Actions has a larger marketplace of pre-made actions, which can speed up setup. GitLab CI is more flexible with runners. For WordPress specifically, all three work fine; the choice often comes down to where your repository already lives. If you are on Bitbucket Cloud, Pipelines is the least friction.
Costs and Limitations
Bitbucket Pipelines has a free tier that includes 50 build minutes per month for the standard plan. That’s enough for a few deployments, but if you push frequently or have long builds, you’ll need a paid plan (per-user pricing) or use self-hosted runners, which don’t count against the free minutes. Self-hosted runners require you to run a small agent on your own server – that adds maintenance but removes time limits. Another limitation: the free tier only allows one concurrent step, so you can’t run parallel jobs unless you pay. Also, the pipeline environment is ephemeral – every step starts from a clean container, so you must install tools each time, which adds time.
Safety and Rollback Strategies
Automated deployment can break a live site. To stay safe, always deploy to a staging environment first, then promote to production via a manual approval step in Bitbucket. Use the deployment: production property and set the trigger to manual for production. Also, keep a backup of the previous version – either via rsync to a backup folder or by tagging the release in Git. If something goes wrong, you can redeploy the previous tag. For database changes, never run destructive SQL automatically; instead, output a SQL file that you review manually. Finally, test the pipeline on a throwaway server before pointing it at your live site.
Frequently Asked Questions
Do I need to use Composer for WordPress deployment?
No. Composer is optional. If you manage your theme and plugins as plain folders, you can deploy them directly with rsync. Composer becomes useful when you want to track WordPress core and plugin versions in a composer.json file, enabling reproducible builds. But it adds a learning curve and a build step. Start without Composer if you’re new.
Can I deploy to shared hosting with Bitbucket Pipelines?
Yes, if the host provides SSH access. Many shared hosts (like SiteGround, Bluehost, Hostinger) offer SSH, but some don’t. Check with your provider. If SSH is not available, you can use SFTP, but that requires installing an SFTP client in the pipeline (e.g., lftp) and handling password authentication, which is less secure. SSH is strongly preferred.
How do I update the database after deployment?
You can run WP-CLI commands on the server via SSH in the pipeline, for example wp db migrate if you use a migration plugin, or wp core update-db to run database updates after a core update. However, be cautious – automated database changes can cause data loss. A safer approach is to run the commands manually after deployment, or use a plugin that handles the changes for you.
What if my theme has build steps like Sass or JavaScript bundling?
Add a build step before deployment. In the pipeline, run npm install and npm run build to generate the final CSS and JS files. Then deploy only the built files. This ensures the server never receives source files. Make sure your build script outputs to a folder that rsync will pick up.
Is it safe to use --delete in rsync?
It is safe only if the local folder is the complete source of truth. If you have files on the server that are not in the repo (like uploads, or generated caches), --delete will remove them. Always exclude such folders with --exclude flags. For example, add --exclude='uploads/' to your rsync command to protect user uploads.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Samsung Smart Speaker Rollable Display: Facts
- HP 9730e: Wide Prints, Not A3 Scans
- What 8888 Does When You Use It as DNS Server
- Credential Manager: Seamless Sign-In Explained
- API Governance for Public Data: What Growing Portfolios Need
- Enterprise AI Hidden Cost: Data Architecture ROI