GitLab CI/CD Integration
Integrate Capgo Live Updates with GitLab CI/CD 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 GitLab CI/CD integration, ensure you have:
- A GitLab account with a project repository
- A Capgo account with an app configured
- Node.js and npm/yarn configured in your project
Setting Up GitLab CI/CD
Step 1: Configure Environment Variables
First, set up the necessary variables in your GitLab project:
- Navigate to your GitLab project
- Go to Settings โ CI/CD โ Variables
- Add the following variables:
Variable Name | Value | Protected | Masked |
---|---|---|---|
CAPGO_TOKEN | Your Capgo API token | โ Yes | โ Yes |
Simple
Basic configuration that deploys to production on every push to the main branch:
# .gitlab-ci.yml - Simple Configurationimage: node:22
stages: - build - deploy
variables: npm_config_cache: "$CI_PROJECT_DIR/.npm"
build: stage: build script: - npm ci - npm run test - npm run build artifacts: paths: - dist/ expire_in: 1 hour only: - main
deploy_production: stage: deploy script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production # For encrypted uploads, add: --key-data-v2 "$CAPGO_PRIVATE_KEY" dependencies: - build only: - main
Advanced
Feature Branch Deployments
Deploy feature branches to test channels for review and testing:
# Feature branch deploymentdeploy_feature: stage: deploy script: - npm install -g @capgo/cli - CHANNEL_NAME="feature-$(echo $CI_COMMIT_REF_NAME | sed 's/[^a-zA-Z0-9-]/-/g')" - npx @capgo/cli channel create $CHANNEL_NAME --apikey $CAPGO_TOKEN || true - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME dependencies: - build only: - /^feature\/.*$/ environment: name: feature/$CI_COMMIT_REF_NAME url: https://your-app.com/channels/$CHANNEL_NAME
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 GitLab variables:
# Display your private key content (copy this output)cat .capgo_key_v2
Add this content as CAPGO_PRIVATE_KEY
in your GitLab project variables (mark as protected and masked), then use it in pipelines:
# Deploy with encryptiondeploy_production: 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 merge request deployments:
# .gitlab-ci.yml - Advanced Multi-Channel Configurationimage: node:22
stages: - build - deploy
variables: npm_config_cache: "$CI_PROJECT_DIR/.npm"
# Build stagebuild: stage: build script: - npm ci - npm run test - npm run build artifacts: paths: - dist/ expire_in: 24 hours
# Deploy to development channeldeploy_development: stage: deploy script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel development dependencies: - build only: - develop environment: name: development
# Deploy merge requests to test channelsdeploy_mr: stage: deploy script: - npm install -g @capgo/cli - CHANNEL_NAME="mr-$CI_MERGE_REQUEST_IID" - npx @capgo/cli channel create $CHANNEL_NAME --apikey $CAPGO_TOKEN || true - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME dependencies: - build only: - merge_requests environment: name: review/$CI_MERGE_REQUEST_IID url: https://your-app.com/channels/mr-$CI_MERGE_REQUEST_IID on_stop: cleanup_mr
# Cleanup MR channels when MR is closedcleanup_mr: stage: deploy script: - npm install -g @capgo/cli - npx @capgo/cli channel delete mr-$CI_MERGE_REQUEST_IID --apikey $CAPGO_TOKEN || true when: manual environment: name: review/$CI_MERGE_REQUEST_IID action: stop only: - merge_requests
# Deploy to stagingdeploy_staging: stage: deploy script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel staging dependencies: - build only: - develop environment: name: staging
# Deploy to productiondeploy_production: stage: deploy script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production dependencies: - build only: - main environment: name: production
Multi-Environment with Manual Approval
For production deployments requiring manual approval:
deploy_production: stage: deploy script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production dependencies: - build only: - main when: manual environment: name: production
Branch-Based Deployment Strategy
Deploy different branches to appropriate channels automatically:
# Dynamic channel deployment based on branchdeploy: stage: deploy script: - npm install -g @capgo/cli - | if [ "$CI_COMMIT_REF_NAME" = "main" ]; then CHANNEL="production" elif [ "$CI_COMMIT_REF_NAME" = "develop" ]; then CHANNEL="staging" else CHANNEL="development" fi - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL dependencies: - build environment: name: $CHANNEL
Security Best Practices
Protected Variables
- Mark Sensitive Variables: Always mark API tokens as protected and masked
- Branch Protection: Use protected variables for production deployments
- Access Control: Limit variable access to maintainers only
- Regular Rotation: Rotate API tokens regularly
Secure Pipeline Configuration
# Use protected variables for productiondeploy_production: stage: deploy script: - npm install -g @capgo/cli - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production only: refs: - main variables: - $CI_COMMIT_REF_PROTECTED == "true"
Monitoring and Notifications
Slack Integration
Add Slack notifications to your pipeline:
notify_success: stage: .post image: alpine:latest before_script: - apk add --no-cache curl script: - | curl -X POST -H 'Content-type: application/json' \ --data '{"text":"โ
Capgo deployment successful for '"$CI_COMMIT_REF_NAME"'"}' \ $SLACK_WEBHOOK_URL when: on_success
notify_failure: stage: .post image: alpine:latest before_script: - apk add --no-cache curl script: - | curl -X POST -H 'Content-type: application/json' \ --data '{"text":"โ Capgo deployment failed for '"$CI_COMMIT_REF_NAME"'"}' \ $SLACK_WEBHOOK_URL when: on_failure
Email Notifications
Configure email notifications in your GitLab project settings or use the API:
notify_email: stage: .post script: - | curl --request POST \ --header "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \ --form "to=team@yourcompany.com" \ --form "subject=Capgo Deployment Status" \ --form "body=Deployment of $CI_COMMIT_REF_NAME completed with status: $CI_JOB_STATUS" \ "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/emails" when: always
Troubleshooting
Common Issues
Pipeline fails with โCapgo CLI not foundโ:
# Debug CLI installationdebug_cli: script: - npm install -g @capgo/cli - which capgo || echo "Capgo CLI not found" - npx @capgo/cli --version
Authentication errors:
# Verify token configurationdebug_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 outputsdebug_build: script: - ls -la dist/ - find dist/ -type f -name "*.js" -o -name "*.html"
Debug Pipeline
Add debugging information to troubleshoot issues:
debug: stage: build script: - echo "Branch: $CI_COMMIT_REF_NAME" - echo "Commit: $CI_COMMIT_SHA" - echo "Build: $CI_PIPELINE_ID" - env | grep CI_ | sort only: - branches
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 GitLab CI/CD integration, you can automate your Capgo deployments and ensure consistent, reliable updates to your mobile app users.