Skip to content

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:

  1. Navigate to your GitLab project
  2. Go to Settings โ†’ CI/CD โ†’ Variables
  3. Add the following variables:
Variable NameValueProtectedMasked
CAPGO_TOKENYour Capgo API tokenโœ… Yesโœ… Yes

Simple

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

# .gitlab-ci.yml - Simple Configuration
image: 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 deployment
deploy_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:

Terminal window
# 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 encryption
deploy_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 Configuration
image: node:22
stages:
- build
- deploy
variables:
npm_config_cache: "$CI_PROJECT_DIR/.npm"
# Build stage
build:
stage: build
script:
- npm ci
- npm run test
- npm run build
artifacts:
paths:
- dist/
expire_in: 24 hours
# Deploy to development channel
deploy_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 channels
deploy_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 closed
cleanup_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 staging
deploy_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 production
deploy_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 branch
deploy:
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

  1. Mark Sensitive Variables: Always mark API tokens as protected and masked
  2. Branch Protection: Use protected variables for production deployments
  3. Access Control: Limit variable access to maintainers only
  4. Regular Rotation: Rotate API tokens regularly

Secure Pipeline Configuration

# Use protected variables for production
deploy_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 installation
debug_cli:
script:
- npm install -g @capgo/cli
- which capgo || echo "Capgo CLI not found"
- npx @capgo/cli --version

Authentication errors:

# Verify token configuration
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
debug_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

With GitLab CI/CD integration, you can automate your Capgo deployments and ensure consistent, reliable updates to your mobile app users.