Skip to main content

Release Management

The release command is the primary way to deploy OTA updates to your React Native applications. This guide covers everything you need to know about releasing updates.

Prerequisites

Before releasing, ensure you have an access key and you are logged in via the CLI.

See the setup steps in the Installation guide (Access Key and Authentication).

Release Types​

There are two ways to ship updates. Choose based on the size of your changes and your rollout needs:

1. Full Bundle​

Ships the entire JavaScript bundle (and assets).

  • Best for large changes, first release, or when the base version changed
  • Most robust: does not require a previous bundle on device
  • Larger download size than a patch

2. Patch Bundle​

Ships only the differences from a known base bundle.

  • Best for small/medium updates where you want minimal download size and faster installs
  • Requires that users already have the referenced base bundle version
  • Must be released with --isPatch true and assets for correctness

Basic Release Command​

yarn code-push-standalone release <appName> <updateContents> <targetBinaryVersion> [options]

Required Parameters​

ParameterDescriptionExample
appNameName of your appMyApp-iOS, MyApp-Android
updateContentsPath to bundle/assets./codepush, ./dist/bundle
targetBinaryVersionApp store version1.0.0, ^1.0.0, *

Optional Parameters​

ParameterDescriptionDefault
--deploymentName, -dTarget deploymentStaging
--description, -desRelease notes-
--disabledPrevent downloadfalse
--mandatoryForce updatefalse
--noDuplicateReleaseErrorWarn instead of error for duplicatesfalse
--rolloutPercentage of users (1-100)100
--isPatch, -pWhether this is a patchfalse
--compression, -cAlgorithm: deflate or brotlideflate

Full Bundle Releases​

Basic Example​

yarn code-push-standalone release MyApp-iOS ./codepush 1.0.0

This will:

  • Deploy to Staging (default)
  • Target app version 1.0.0 exactly
  • Use deflate compression
  • Release to 100% of users

Production Release​

yarn code-push-standalone release MyApp-iOS ./codepush 1.0.0 \
  --deploymentName Production \
  --description "New features and fixes" \
  --mandatory

Release with Version Range​

Use semver to target multiple versions:

# Compatible with all 1.x.x versions
yarn code-push-standalone release MyApp-iOS ./codepush "^1.0.0" \
  --deploymentName Production

# Compatible with specific range
yarn code-push-standalone release MyApp-iOS ./codepush ">=1.0.0 <2.0.0" \
  --deploymentName Production

# All versions
yarn code-push-standalone release MyApp-iOS ./codepush "*" \
  --deploymentName Production

Gradual Rollout​

Release to a percentage of users:

# Start with 25% of users
yarn code-push-standalone release MyApp-iOS ./codepush 1.0.0 \
  --deploymentName Production \
  --rollout 25 \
  --description "New feature rollout"

Then increase the rollout:

# Later, increase to 50%
yarn code-push-standalone patch MyApp-iOS Production \
  --rollout 50

# Finally, 100%
yarn code-push-standalone patch MyApp-iOS Production \
  --rollout 100

Using Brotli Compression​

Brotli provides better compression than deflate:

yarn code-push-standalone release MyApp-iOS ./dist/bundle "^1.0.0" \
  --deploymentName Production \
  --compression brotli \
  --description "Compressed with Brotli for faster downloads"

Compression Comparison:

  • Deflate: Standard compression (e.g., 23.1MB → 11.04MB)
  • Brotli: Better compression (e.g., 23.1MB → 8.14MB)
Recommendation

Use Brotli for production releases to minimize download times and bandwidth usage.

Patch Bundle Releases​

Patch bundles significantly reduce update size by sending only the changes between versions.

Step 1: Create Patch​

First, create a patch between the old and new bundles:

yarn code-push-standalone create-patch \
  ./old-bundle \
  ./new-bundle \
  ./.codepush/patches

Parameters:

  • ./old-bundle: Path to the previous version's bundle
  • ./new-bundle: Path to the new version's bundle
  • ./.codepush/patches: Output directory for the patch

Step 2: Release Patch​

Then release the patch bundle:

yarn code-push-standalone release MyApp-iOS ./.codepush/patches "1.0.0" \
  --deploymentName Staging \
  --description "Bug fixes (patch)" \
  --isPatch true \
  --compression brotli
Important

Always use --isPatch true when releasing a patch bundle, and include assets alongside the patch bundle.

Benefits of Patch Releases​

  • Smaller Download Size: Only diff is transferred
  • Faster Updates: Quicker download and installation
  • Reduced Bandwidth: Lower costs and data usage
  • Better UX: Less waiting time for users

Example: Patch vs Full Bundle​

Full Bundle:   23.1 MB → 8.14 MB (with Brotli)
Patch Bundle:  23.1 MB → 2.3 MB (90% reduction!)

Advanced Release Scenarios​

Multi-Platform Release​

Deploy to both iOS and Android:

# iOS
yarn code-push-standalone release MyApp-iOS ./ios-bundle 1.0.0 \
  --deploymentName Production \
  --description "Multi-platform release"

# Android
yarn code-push-standalone release MyApp-Android ./android-bundle 1.0.0 \
  --deploymentName Production \
  --description "Multi-platform release"

Disabled Release​

Create a release but prevent it from being downloaded (useful for preparation):

yarn code-push-standalone release MyApp-iOS ./codepush 1.0.0 \
  --deploymentName Production \
  --disabled \
  --description "Prepared for tomorrow's launch"

Mandatory Critical Update​

Force all users to update immediately:

yarn code-push-standalone release MyApp-iOS ./codepush 1.0.0 \
  --deploymentName Production \
  --mandatory \
  --description "Critical security fix - mandatory update"

No Duplicate Error​

Prevent errors when releasing the same content (useful in automated pipelines):

yarn code-push-standalone release MyApp-iOS ./codepush 1.0.0 \
  --noDuplicateReleaseError \
  --description "Release (safe for duplicate)"

Promoting Releases​

After testing in Staging, promote to Production:

Basic Promotion​

yarn code-push-standalone promote MyApp-iOS Staging Production

Promotion with Options​

yarn code-push-standalone promote MyApp-iOS Staging Production \
  --rollout 25 \
  --description "Verified in staging - releasing to 25% of production users"

Monitoring Releases​

View Deployment History​

yarn code-push-standalone deployment history MyApp-iOS Staging

List All Deployments​

yarn code-push-standalone deployment list MyApp-iOS

Release Workflow Examples​

Development Workflow​

# 1. Deploy to staging for testing
yarn code-push-standalone release MyApp-iOS ./codepush ^1.0.0 \
  -d Staging \
  -des "Testing new feature"

# 2. Test thoroughly

# 3. Promote to production with gradual rollout
yarn code-push-standalone promote MyApp-iOS Staging Production --rollout 25

# 4. Monitor metrics

# 5. Increase rollout
yarn code-push-standalone patch MyApp-iOS Production --rollout 100

Hotfix Workflow​

# Urgent bug fix - deploy immediately to all users
yarn code-push-standalone release MyApp-iOS ./hotfix-bundle 1.0.0 \
  -d Production \
  --mandatory \
  --compression brotli \
  -des "Critical bug fix"

Patch Release Workflow​

# 1. Create patch
yarn code-push-standalone create-patch \
  ./previous-bundle \
  ./new-bundle \
  ./.codepush/patches

# 2. Deploy patch to staging
yarn code-push-standalone release MyApp-iOS ./.codepush/patches 1.0.0 \
  -d Staging \
  --isPatch true \
  -des "Small bug fixes"

# 3. Test

# 4. Promote to production
yarn code-push-standalone promote MyApp-iOS Staging Production

Best Practices​

1. Always Test in Staging First​

# ✅ Good: Test first
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 -d Staging
# ... test thoroughly ...
yarn code-push-standalone promote MyApp-iOS Staging Production

# ❌ Bad: Direct to production
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 -d Production

2. Use Semantic Versioning​

# ✅ Good: Flexible targeting
yarn code-push-standalone release MyApp-iOS ./bundle "^1.0.0" -d Production

# ⚠️ OK: Exact version (more restrictive)
yarn code-push-standalone release MyApp-iOS ./bundle "1.0.0" -d Production

# ❌ Avoid: Too broad
yarn code-push-standalone release MyApp-iOS ./bundle "*" -d Production

3. Gradual Rollouts for Major Changes​

# ✅ Good: Gradual rollout
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 \
  -d Production \
  --rollout 10 \
  -des "Major feature update"

# ❌ Risky: All users immediately
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 \
  -d Production

4. Use Brotli for Production​

# ✅ Good: Better compression
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 \
  -d Production \
  --compression brotli

# ⚠️ OK: Default compression
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 -d Production

5. Descriptive Release Notes​

# ✅ Good: Clear description
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 \
  -d Production \
  -des "v1.2.0: Fixed login bug, improved image loading performance"

# ❌ Bad: No context
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0 -d Production

Common Pitfalls​

1. Wrong App Name​

# ❌ Error: App not found
yarn code-push-standalone release MyApp ./bundle 1.0.0

# ✅ Correct: Use exact app name from dashboard
yarn code-push-standalone release MyApp-iOS ./bundle 1.0.0

2. Version Mismatch​

# ❌ Error: App version 1.5.0 doesn't match target 1.0.0
yarn code-push-standalone release MyApp-iOS ./bundle "1.0.0"

# ✅ Correct: Match or use range
yarn code-push-standalone release MyApp-iOS ./bundle "^1.0.0"

3. Forgot isPatch Flag​

# ❌ Error: Will treat patch as full bundle
yarn code-push-standalone release MyApp-iOS ./patch-bundle 1.0.0

# ✅ Correct: Specify isPatch
yarn code-push-standalone release MyApp-iOS ./patch-bundle 1.0.0 --isPatch true