Deploying WordPress with Bitbucket: A Complete Guide to Automated Deployments

Manual FTP uploads have no place in modern WordPress development workflows. The risks of human error, lack of version control, and inability to track changes make traditional deployment methods unsustainable for professional teams. Bitbucket Pipelines offers a robust solution for automating WordPress deployments, allowing developers to push code changes and have them automatically deployed to production servers without manual intervention.

This guide covers everything from initial setup to advanced deployment strategies, helping teams establish reliable, repeatable deployment processes that scale with their projects. By implementing automated deployment workflows, development teams can focus on building features rather than managing manual upload processes.

Why Use Bitbucket Pipelines for WordPress Deployments

The Case for Automated Deployments

Traditional WordPress deployment methods rely heavily on manual file transfers via FTP or cPanel file managers. While these approaches work for small, static websites, they introduce significant risks and inefficiencies as projects grow.

Key problems with manual deployments:

• Human error in uploading files to wrong locations
• Overwriting customizations during core updates
• Missing critical files in the transfer process
• No version control history for recovery
• Time-consuming repetitive tasks

Automated deployment through Bitbucket Pipelines addresses these challenges by treating every deployment as an auditable, repeatable process. Each push triggers a defined workflow executing the same steps in the same order, eliminating variability.

Bitbucket Pipelines as a Preferred Solution

Bitbucket Pipelines stands out due to its tight integration with Atlassian tools and flexible YAML-based configuration:

• Configuration lives within the repository (bitbucket-pipelines.yml)
• Deployment processes are version-controlled alongside codebase
• The atlassian/ssh-run pipe simplifies server connections
• Free tier includes sufficient build minutes for many WordPress projects
• Repository variables provide encrypted credential storage

For teams investing in professional web development services, automated deployment becomes essential for maintaining code quality and deployment consistency across projects.

Comparing Deployment Options

For teams already using Bitbucket or wanting maximum control over their deployment process, Bitbucket Pipelines provides a powerful, flexible foundation that can be extended to meet specialized requirements.

Preparing Your WordPress Site for Bitbucket Deployment

Assessing Your Current Setup

Before configuring Bitbucket Pipelines, evaluate your existing WordPress installation:

Checklist for deployment readiness:

• Database credentials externalized (not hardcoded in wp-config.php)
• API keys stored in environment variables or .env files
• Custom themes and plugins identified for version control
• Non-version-controlled content (uploads, cache) separated

Creating a Proper .gitignore File

A well-crafted .gitignore prevents accidental tracking of non-code files:

# WordPress core - exclude if managed by host
exclude:false

# Exclude these entirely
wp-content/uploads/
wp-content/cache/
wp-content/backupwordpress-*/
*.log
wp-content/debug.log

# Optional: exclude core if installed separately
wp-admin/
wp-includes/
index.php
wp-login.php
wp-*.php

# Track custom code
!wp-content/themes/your-custom-theme/
!wp-content/plugins/your-custom-plugin/
!wp-content/mu-plugins/

Organizing Your Repository Structure

The repository structure affects how easily you can manage deployments and maintain the codebase over time. For most WordPress projects, this structure works well:

/
├── wp-content/
│ ├── themes/
│ │ └── your-custom-theme/
│ │ ├── style.css
│ │ ├── functions.php
│ │ ├── index.php
│ │ └── assets/
│ │ ├── css/
│ │ ├── js/
│ │ └── images/
│ ├── plugins/
│ │ └── your-custom-plugin/
│ │ ├── your-custom-plugin.php
│ │ └── includes/
│ └── mu-plugins/
│ └── sitewide-require.php
├── .gitignore
├── bitbucket-pipelines.yml
├── composer.json (if using)
└── README.md

Place custom themes in wp-content/themes/ and track them fully, including source files like Sass or TypeScript that compile to CSS and JavaScript. Keep custom plugins in wp-content/plugins/ with complete tracking. Consider adding a project-level README documenting the deployment process, any required environment variables, and notes on server configuration. This documentation becomes invaluable when onboarding new team members or troubleshooting deployment issues months after initial setup.

SSH Authentication Configuration

Understanding SSH for Automated Deployments

SSH (Secure Shell) provides the secure tunnel for Bitbucket Pipelines to connect to your WordPress server. The process uses cryptographic key pairs:

• Private key remains secure on the Bitbucket side (stored in repository variables)
• Public key gets added to authorized_keys on your server

Generating SSH Keys for Deployment

Generate a dedicated key pair for deployment:

ssh-keygen -t ed25519 -C "[email protected]"

Save to a descriptive path like ~/.ssh/id_ed25519_wordpress_deploy. Skip the passphrase for automated deployments.

Adding Public Keys to Authorized Servers

For managed hosts like Kinsta:

1. Navigate to User Settings > SSH Keys in MyKinsta
2. Paste the public key content

For self-managed servers:

cat ~/.ssh/id_ed25519_wordpress_deploy.pub >> ~/.ssh/authorized_keys

Configuring Repository Variables in Bitbucket

Navigate to Repository Settings > Repository Variables and add:

Generate base64-encoded key:

cat ~/.ssh/id_ed25519_wordpress_deploy | base64

These variables are encrypted at rest and available only during pipeline execution, providing secure credential handling without exposing sensitive information in logs or configuration files.

Configuring Bitbucket Pipelines

Creating the Pipeline Configuration File

Create bitbucket-pipelines.yml in your repository root:

pipelines:
 branches:
 main:
 - step:
 name: Deploy to Production
 script:
 - pipe: atlassian/ssh-run:0.8.1
 variables:
 SSH_USER: $KINSTA_USERNAME
 SERVER: $KINSTA_SERVER_IP
 PORT: $PORT
 COMMAND: |
 cd /www/your-site/public
 git fetch origin main
 git reset --hard origin/main
 SSH_KEY: $SSH_PRIVATE_KEY
 DEBUG: 'true'

Understanding Pipeline Structure

• branches: Defines trigger conditions (pushes to main)
• step: Individual pipeline stages
• script: Commands executed via the ssh-run pipe
• pipe: Pre-built integration for common tasks

Customizing the Deployment Script

Enhance deployments with WordPress-specific commands:

cd /www/your-site/public
git fetch origin main
git reset --hard origin/main

# Clear WordPress cache
wp cache flush --allow-root 2>/dev/null || true

# Flush rewrite rules if needed
wp rewrite flush --allow-root 2>/dev/null || true

# Activate theme if changed
wp theme activate your-theme --allow-root 2>/dev/null || true

Environment-Specific Configurations

For projects with multiple environments, extend the pipeline to handle each appropriately:

pipelines:
 branches:
 develop:
 - step:
 name: Deploy to Development
 script:
 - pipe: atlassian/ssh-run:0.8.1
 variables:
 SSH_USER: $DEV_USERNAME
 SERVER: $DEV_SERVER_IP
 PORT: $DEV_PORT
 COMMAND: |
 cd /www/dev-site/public
 git fetch origin develop
 git reset --hard origin/develop
 SSH_KEY: $DEV_SSH_KEY
 main:
 - step:
 name: Deploy to Production
 script:
 - pipe: atlassian/ssh-run:0.8.1
 variables:
 SSH_USER: $PROD_USERNAME
 SERVER: $PROD_SERVER_IP
 PORT: $PROD_PORT
 COMMAND: |
 cd /www/prod-site/public
 git fetch origin main
 git reset --hard origin/main
 SSH_KEY: $PROD_SSH_KEY

This setup deploys pushes to develop to a development environment and main to production, using separate credentials for each. Implementing this approach as part of a comprehensive web development strategy ensures consistent deployment practices across all your projects.

Deployment Workflow and Best Practices

The Complete Deployment Process

Local Development

git checkout -b feature/update-header
git add wp-content/themes/your-theme/
git commit -m "Update header styles"
git push origin feature/update-header

After Merge to Main:

1. Bitbucket receives push to main
2. Pipeline execution begins
3. SSH connection establishes to server
4. Commands execute in sequence
5. Pipeline logs capture the process
6. Changes are live on production

Handling WordPress-Specific Assets

Media files in wp-content/uploads/ exist separately from code and shouldn't be overwritten by deployment.

wp-config.php often contains environment-specific values - keep it out of git or use a deployment strategy that preserves existing configuration:

cp wp-config.php wp-config.php.bak
git checkout HEAD -- wp-content/themes/ wp-content/plugins/
mv wp-config.php.bak wp-config.php

Database Considerations

For database changes accompanying code updates:

• Manual updates through admin/WP-CLI for small changes
• Version-controlled migration scripts for complex schema changes
• Separate database deployment tools for large migrations

Testing Before Deployment

Integrate automated testing:

- step:
 name: Run Tests
 script:
 # PHP syntax check
 - find . -name "*.php" -print0 | xargs -0 -n1 -P4 php -l
 # Custom test suites
 - phpunit -c wp-content/themes/your-theme/phpunit.xml || true

Advanced Deployment Strategies

Blue-Green Deployments

Blue-green deployment maintains two identical environments, switching traffic between them:

1. Maintain two WordPress installations (blue and green)
2. Use load balancer to direct traffic to active environment
3. Deploy to inactive environment
4. Switch traffic after verification
5. Keep previous environment as rollback target

Simpler approach using timestamped directories:

DEPLOY_DIR="/www/your-site/releases/$(date +%Y%m%d_%H%M%S)"
mkdir -p $DEPLOY_DIR
git clone --depth 1 file:///www/your-site/repo.git $DEPLOY_DIR
ln -sfn $DEPLOY_DIR /www/your-site/public

Canary Deployments

Gradually shift traffic to new code while monitoring for issues:

1. Deploy new code to subset of servers
2. Route small percentage (1-5%) of traffic to canary
3. Monitor error rates and performance metrics
4. Gradually increase traffic if metrics remain healthy
5. Roll back if problems emerge

Rollback Procedures

Git-based rollback:

git reset --hard origin/main^

Directory-based rollback:

ln -sfn /www/your-site/releases/previous_release /www/your-site/public

Database rollback:

wp db import backup_before_deployment.sql --allow-root

Troubleshooting Common Issues

SSH Connection Problems

"Permission denied"

• Public key not in server's authorized_keys
• Wrong username configured
• Verify key was added to correct user account

"Connection timed out"

• Server IP or port incorrect
• Firewall blocking connections
• Check server details in hosting control panel

"Host key verification failed"

• Server's host key changed after rebuilds
• Clear known_hosts entry if needed

Enable DEBUG mode for detailed logging:

DEBUG: 'true'

Git Operation Failures

"not a git repository"

cd /www/your-site/public
git init
git remote add origin <bitbucket-repository-url>

"could not resolve host"

• Verify URL format uses SSH ([email protected]:user/repo.git)

Permission Issues

# Check ownership
ls -la /www/your-site/public/

# Fix ownership
chown -R deploy-user:www-data /www/your-site/public/

Caching and State Issues

Include cache clearing in deployment:

wp cache flush --allow-root
wp rocket flush --allow-root 2>/dev/null || true

Security Considerations

Credential Management

Never commit credentials to version control. Use repository variables for:

• SSH private keys
• API tokens for external services
• Database passwords
• Salt keys and authentication salts

Repository variables are encrypted at rest and masked in logs.

Access Control

• Restrict repository write access to authorized team members
• Require pull request reviews before merging to protected branches
• Configure branch permissions to prevent direct pushes to production
• Use Bitbucket's deployment environments to track deployments

Network Security

For servers with IP allowlists, Bitbucket Pipelines may be blocked:

• Disable IP allowlists for deployment-triggered connections
• Use a middleman server with static IP if needed
• Check hosting provider documentation for automated tool connections

Monitoring and Alerting

• Configure pipeline notifications (email, Slack)
• Implement uptime monitoring for deployed sites
• Track error rates before and after deployment
• Establish alert thresholds for unusual behavior

Following these security practices helps maintain the integrity of your web development infrastructure and protects your deployed applications from common vulnerabilities.

Maintaining Your Deployment Pipeline

Regular Maintenance Tasks

Update pipeline dependencies

• Check for new ssh-run pipe versions
• Update configuration to use latest stable versions

Test rollback procedures

• Practice rollback regularly
• Document any changes discovered during testing

Review deployment logs

• Check for warnings or anomalies
• Identify emerging issues early

Rotate credentials

• Follow security best practices for periodic rotation
• Update repository variables when rotating

Documentation and Knowledge Transfer

Maintain documentation for any team member:

• Document the deployment process in README
• Note host-specific configurations
• Record backup and rollback procedures
• Keep contact information for team members familiar with setup

Scaling the Pipeline

As projects grow, consider:

• Parallel test execution for faster feedback
• Environment promotion (dev -> staging -> production)
• Integration with monitoring platforms
• Deployment approvals for production changes
• Progressive rollouts for high-risk changes

Conclusion

Deploying WordPress with Bitbucket Pipelines transforms deployment from a manual, error-prone process into an automated, reliable workflow. By configuring SSH authentication, creating pipeline configurations, and following best practices for WordPress-specific deployment considerations, teams achieve consistent deployments with minimal effort.

The initial setup requires investment in understanding SSH, Git, and pipeline configuration, but the returns compound over time:

• Every deployment executes identically, reducing human error
• Complete deployment history enables easy rollback
• Pipeline serves as living documentation of deployment process

Start with a basic configuration that deploys on push to main. Refine based on operational experience:

• Add testing gates to catch issues early
• Implement environment-specific configurations
• Adopt advanced deployment strategies as needed

The foundation Bitbucket Pipelines provides scales with your needs while maintaining the simplicity that makes automated deployment accessible for projects of any size.

---

Related Resources:

• WordPress Theme Development Best Practices
• Using Local with Flywheel for Development
• Customizing WordPress Admin