Skip to content

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:

  1. Navigate to your Bitbucket repository
  2. Go to Repository settings โ†’ Pipelines โ†’ Repository variables
  3. Add the following variables:
Variable NameValueSecured
CAPGO_TOKENYour Capgo API tokenโœ… Yes

Simple

Basic configuration that deploys to production on every push to the main branch:

# bitbucket-pipelines.yml - Simple Configuration
image: 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 deployment
pipelines:
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:

Terminal window
# 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 Configuration
image: 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 pipeline
image: 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 deployment
image: 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 pipeline
image: 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

  1. Secured Variables: Always mark API tokens as secured
  2. Environment Variables: Use deployment-specific variables when needed
  3. Access Control: Limit repository access to authorized team members
  4. Token Rotation: Regularly rotate your Capgo API tokens

Deployment Environments

Configure deployment environments for better security:

# Deployment with environment restrictions
pipelines:
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 notifications
pipelines:
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 pipeline
pipelines:
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 validation
options:
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

With Bitbucket Pipelines integration, you can automate your Capgo deployments and ensure consistent, reliable updates to your mobile app users.