Bitbucket Pipelines Integration
Integrate Capgo Live Updates with Bitbucket Pipelines to automatically deploy your app updates whenever you push code changes. This guide covers setting up automated builds, testing, and deployment workflows.
Prerequisites
Before setting up Bitbucket Pipelines integration, ensure you have:
- A Bitbucket account with a repository
- A Capgo account with an app configured
- Node.js and npm/yarn configured in your project
Setting Up Bitbucket Pipelines
Step 1: Configure Repository Variables
First, set up the necessary variables in your Bitbucket repository:
- Navigate to your Bitbucket repository
- Go to Repository settings โ Pipelines โ Repository variables
- Add the following variables:
Variable Name | Value | Secured |
---|---|---|
CAPGO_TOKEN | Your Capgo API token | โ Yes |
Simple
Basic configuration that deploys to production on every push to the main branch:
# bitbucket-pipelines.yml - Simple Configurationimage: node:22
pipelines: branches: main: - step: name: Build and Deploy to Production script: - npm ci - npm run test - npm run build - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production artifacts: - dist/**
Advanced
Feature Branch Deployments
Deploy feature branches to test channels for review and testing:
# Feature branch deploymentpipelines: branches: feature/*: - step: name: Deploy Feature Branch script: - npm ci - npm run test - npm run build - BRANCH_NAME=$(echo $BITBUCKET_BRANCH | sed 's/[^a-zA-Z0-9-]/-/g') - CHANNEL_NAME="feature-$BRANCH_NAME" - npm install -g @capgo/cli - npx @capgo/cli channel create $CHANNEL_NAME --apikey $CAPGO_TOKEN || true - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME artifacts: - dist/**
Using Encryption
If youโre using Capgoโs encryption feature, youโll need to store your private key securely in your CI/CD environment.
After setting up encryption keys locally, add your private key to Bitbucket variables:
# Display your private key content (copy this output)cat .capgo_key_v2
Add this content as CAPGO_PRIVATE_KEY
in your Bitbucket repository variables (mark as secured), then use it in pipelines:
# Deploy with encryption- step: name: Deploy to Capgo with Encryption script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --key-data-v2 "$CAPGO_PRIVATE_KEY" --channel production
Multi-Channel Configuration
For comprehensive information about setting up and managing multiple deployment channels, see the Channels documentation.
Complete configuration with multiple environments and pull request deployments:
# bitbucket-pipelines.yml - Advanced Multi-Channel Configurationimage: node:22
definitions: steps: - step: &build-step name: Build Application script: - npm ci - npm run test - npm run build artifacts: - dist/**
- step: &deploy-step name: Deploy to Capgo script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
pipelines: branches: main: - step: <<: *build-step - step: <<: *deploy-step name: Deploy to Production deployment: production trigger: manual script: - export CHANNEL_NAME=production - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
develop: - step: <<: *build-step - step: <<: *deploy-step name: Deploy to Development deployment: development script: - export CHANNEL_NAME=development - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
pull-requests: '**': - step: <<: *build-step - step: name: Deploy PR to Test Channel script: - CHANNEL_NAME="pr-$BITBUCKET_PR_ID" - npm install -g @capgo/cli - npx @capgo/cli channel create $CHANNEL_NAME --apikey $CAPGO_TOKEN || true - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME artifacts: - dist/**
Multi-Environment Pipeline
For complex deployment scenarios with staging and production environments:
# Multi-environment pipelineimage: node:22
pipelines: branches: main: - step: name: Build script: - npm ci - npm run test - npm run build artifacts: - dist/** - step: name: Deploy to Staging deployment: staging script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel staging - step: name: Deploy to Production deployment: production trigger: manual script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
develop: - step: name: Build and Deploy to Development script: - npm ci - npm run test - npm run build - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel development artifacts: - dist/**
Branch-Based Deployment Strategy
Automatically deploy different branches to appropriate channels:
# Dynamic channel deploymentimage: node:22
definitions: scripts: - script: &determine-channel | if [ "$BITBUCKET_BRANCH" = "main" ]; then export CHANNEL_NAME="production" elif [ "$BITBUCKET_BRANCH" = "develop" ]; then export CHANNEL_NAME="staging" else export CHANNEL_NAME="development" fi echo "Deploying to channel: $CHANNEL_NAME"
pipelines: default: - step: name: Build and Deploy script: - npm ci - npm run test - npm run build - *determine-channel - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME artifacts: - dist/**
Parallel Pipeline Execution
Optimize build times with parallel steps:
# Parallel execution pipelineimage: node:22
pipelines: branches: main: - parallel: - step: name: Run Tests script: - npm ci - npm run test - step: name: Lint Code script: - npm ci - npm run lint - step: name: Build Application script: - npm ci - npm run build artifacts: - dist/** - step: name: Deploy to Production deployment: production script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
Security Best Practices
Repository Variables
- Secured Variables: Always mark API tokens as secured
- Environment Variables: Use deployment-specific variables when needed
- Access Control: Limit repository access to authorized team members
- Token Rotation: Regularly rotate your Capgo API tokens
Deployment Environments
Configure deployment environments for better security:
# Deployment with environment restrictionspipelines: branches: main: - step: name: Deploy to Production deployment: production trigger: manual script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
Monitoring and Notifications
Slack Integration
Add Slack notifications to your pipeline:
# Pipeline with Slack notificationspipelines: branches: main: - step: name: Build and Deploy script: - npm ci - npm run test - npm run build - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production after-script: - | if [ $BITBUCKET_EXIT_CODE -eq 0 ]; then curl -X POST -H 'Content-type: application/json' \ --data '{"text":"โ
Capgo deployment successful for '$BITBUCKET_BRANCH'"}' \ $SLACK_WEBHOOK_URL else curl -X POST -H 'Content-type: application/json' \ --data '{"text":"โ Capgo deployment failed for '$BITBUCKET_BRANCH'"}' \ $SLACK_WEBHOOK_URL fi
Email Notifications
Configure email notifications through Bitbucketโs built-in features or using external services:
# Email notification step- step: name: Send Notification script: - | curl -X POST \ -H "Content-Type: application/json" \ -d '{ "to": "team@yourcompany.com", "subject": "Capgo Deployment Status", "body": "Deployment of '$BITBUCKET_BRANCH' completed with status: '$BITBUCKET_EXIT_CODE'" }' \ $EMAIL_SERVICE_URL condition: result: [successful, failed]
Troubleshooting
Common Issues
Pipeline fails with โCapgo CLI not foundโ:
# Debug CLI installation- step: name: Debug CLI script: - npm install -g @capgo/cli - which capgo || echo "Capgo CLI not found" - npx @capgo/cli --version
Authentication errors:
# Verify token configuration- step: name: Debug Auth script: - | if [ -z "$CAPGO_TOKEN" ]; then echo "CAPGO_TOKEN is not set" exit 1 fi echo "Token length: ${#CAPGO_TOKEN}"
Build artifacts not found:
# List build outputs- step: name: Debug Build script: - ls -la dist/ - find dist/ -type f -name "*.js" -o -name "*.html"
Debug Pipeline
Add debugging information to troubleshoot issues:
# Debug pipelinepipelines: branches: main: - step: name: Debug Information script: - echo "Branch: $BITBUCKET_BRANCH" - echo "Commit: $BITBUCKET_COMMIT" - echo "Build: $BITBUCKET_BUILD_NUMBER" - env | grep BITBUCKET_ | sort - step: name: Build and Deploy script: - npm ci - npm run test - npm run build - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
Pipeline Validation
Enable pipeline validation to catch configuration errors:
# Enable pipeline validationoptions: docker: true size: 2x
pipelines: branches: main: - step: name: Validate Pipeline script: - echo "Pipeline validation successful" - step: name: Build and Deploy script: # ... deployment steps
Next Steps
- Learn about Channels to manage different deployment environments
- Explore Custom Storage for advanced deployment scenarios
- Set up Encryption for secure deployments
- Configure Update Behavior to customize how updates are applied
With Bitbucket Pipelines integration, you can automate your Capgo deployments and ensure consistent, reliable updates to your mobile app users.