Building and Shipping a React Native iOS App with Jenkins: A Practical, End-to-End Pipeline

If you’re maintaining a React Native monorepo and need a repeatable, one-click iOS build pipeline, this post walks you through a production-grade Jenkins setup that:

• Selects environments, schemas, and configs at build time
• Installs dependencies (Node, Ruby/Bundler, CocoaPods) cleanly
• Archives and exports an IPA via xcodebuild
• Uploads artifacts to Amazon S3
• Generates a pre-signed download URL
• Notifies your team on Google Chat

We’ll break down the entire Jenkinsfile, explain each stage, and point out gotchas and improvements for reliability and security.

All examples below are adapted for a React Native app living at ../packages/mobile/ios using an Xcode scheme MyDemoProject. Swap names/paths to your project accordingly.

Why Jenkins for RN iOS?

Deterministic builds: pinned Node/Ruby versions and clean workspaces reduce “works on my machine” issues.
Self-hosted Macs: iOS signing and xcodebuild require macOS. Jenkins agents (or nodes) let you scale across Mac minis.
Flexible fan-out: build multiple schemas/environments without duplicating jobs.
First-class artifacts: archive IPAs, push to S3, create immutable build traceability.

High-Level Flow

• Parameterized Build – Developer selects ENV, SCHEMA, Configuration, GIT_BRANCH, and adds release notes.
• Checkout – Clone the requested Git branch.
• Provisioning Setup – Install the Provisioning Profile and Signing Certificate on the system. This can be done manually or automated through a script.
• Install & Prepare – Run Yarn install, Bundler, and CocoaPods. Apply signing values to the Xcode project as needed.
• ExportOptions.plist – This file is required for IPA export. Create and configure it with details such as distribution method, Team ID, and provisioning profiles. (For a detailed reference, consult Apple’s documentation or the guide linked earlier.)
• Build – Run xcodebuild clean, archive the project, and export the IPA using -exportArchive.
• Rename & Upload – Append a timestamp to the IPA filename, upload it to S3, and generate a pre-signed URL.
• Notify – Post a build notification (with environment, branch, configuration, and download link) to Google Chat, Slack, or Teams.
• Archive & Cleanup – Store artifacts in Jenkins for auditing and wipe the workspace to prepare for the next run.

The Jenkinsfile (Annotated)

What Each Stage Does (and RN-specific Notes)

Parameters

• ENV: Controls environment-specific code paths (API endpoints, flags).
• SCHEMA: Ties to Xcode’s scheme configuration. For prod, use Release; for others, use Staging.Release.
• Configuration: Guards against debug builds in production.
• GIT_BRANCH: Allows building hotfix branches quickly.
• RELEASE_NOTES: Sent to Chat; useful for auditing the why behind a build.

Cleaning the Workspace

• Ensures a fresh build (no stale Pods or derived data leaking across jobs). Consider enabling Jenkins Workspace Cleanup globally.

Checkout

• Clones the exact branch requested. In monorepos, this avoids copying gigabytes across nodes by letting Git do shallow fetches if you set them.

Install Dependencies & Build

• Yarn install: Clear locks to break bad lockfiles (optional; you may prefer keeping lockfiles for determinism).
• Ruby/Bundler/Pods: Pin via Gemfile and Podfile.lock. Use bundle exec pod install.
• Signing edits via sed: Works, but prefer .xcconfig or Xcode Build Settings per configuration to avoid editing project.pbxproj at runtime.

Environment:

• NODE_OPTIONS=–openssl-legacy-provider helps certain crypto libs on Node 17/18/20.
• LANG/LC_ALL set to avoid locale-related pod issues.
• RCT_NO_LAUNCH_PACKAGER=1 disables Metro during CI (faster, fewer logs).

xcodebuild:

• archive writes to ~/Library/Developer/Xcode/Archives/<date>/VideoReady.xcarchive.
• -exportArchive uses ExportOptions.plist (set your method: app-store, ad-hoc, enterprise, etc.).

Rename IPA

• Adds a timestamp: sooka_YYYYMMDD_HHMMSS.ipa. Helps with traceability.

Upload to S3

• Uploads the IPA to s3://<bucket>/<name>.ipa. Lock down the bucket with IAM; do not make it public.

Pre-signed URL & Notification

• Pre-signed URL (e.g., 20 hours = 72,000 seconds) shared with the team.
• Google Chat card with job info, branch, environment, configuration, and download link.
• Use Jenkins Credentials for the Chat webhook: never hard-code URLs or tokens.

Post Actions

• archiveArtifacts keeps a copy inside Jenkins for auditing.
• cleanWs ensures next build is pristine.

Security & Reliability Best Practices

1. Move all secrets to Jenkins Credentials
   • KEYCHAIN_PASSWORD, S3 credentials, Google Chat webhook, Git deploy key.
   • Use withCredentials blocks (usernamePassword, string, sshUserPrivateKey).
2. Don’t sed your project file in CI
   • Prefer xcconfigs and per-config build settings, or pass settings as xcodebuild arguments (PROVISIONING_PROFILE_SPECIFIER=… CODE_SIGN_STYLE=Manual).
3. Pin Tooling Versions
   • Node with volta/nvm + .nvmrc.
   • Ruby with .ruby-version (+ Bundler).
   • CocoaPods version in Gemfile to avoid “works yesterday, breaks today”.
4. Cache Wisely
   • Cache Pods/ and ~/Library/Caches/CocoaPods to speed up builds.
   • Cache Yarn modules (~/.cache/yarn) per Node version.
   • In Jenkins, use node labels (e.g., macos-m1) and persistent workspaces with @libs caches.
5. Code Signing
   • Consider fastlane match to manage certs and profiles via a private repo.
   • Unlock keychain using credentials; import certificates & profiles during the job.
6. Split Mono Stages
   • Create dedicated stages for “Prepare Signing”, “Pods Install”, “Build”. Easier to spot failures and to retry a single stage.
7. Logging & Metrics
   • Pipe xcodebuild through xcbeautify or xcpretty for readable logs.
   • Emit build metadata (ENV, SCHEMA, commit SHA) to your observability system.

Common Pitfalls (and Fixes)

1. Pod install fails on CI, works locally
   • Pin CocoaPods via Bundler; ensure LANG and LC_ALL are set; make sure Xcode command line tools are selected (xcode-select -p).
2. Code signing intermittent
   • Use automatic signing per target only in dev. For CI, keep manual signing and consistent profiles.
3. Metro bundler launches
   • Ensure RCT_NO_LAUNCH_PACKAGER=1 and no “Run Script” phase starts Metro for Release.
4. Wrong scheme/config used
   • Verify your .xcscheme contains the expected buildConfiguration. Avoid editing with sed; keep source-controlled .xcscheme variants.

What to Improve Next

• Fastlane wrappers: fastlane gym for building/exporting; fastlane run for S3 upload and Chat notifications.
• Parallelization: matrix builds per ENV or per device family.
• Distribution: integrate with TestFlight or enterprise MDM if required.

Summary:

1. This Jenkins pipeline gives you:
   • Parameter-driven iOS builds for multiple environments/schemas
   • Clean dependency setup for React Native (Yarn + Bundler + Pods)
   • Reliable xcodebuild archive/export with controllable signing
   • Artifact storage on S3 and instant team notifications
   • Clean archives and reproducible runs

If you’d like to implement a similar setup for your React Native iOS builds, feel free to connect with me — I’ll be happy to guide you through the entire process. I worked closely with a DevOps engineer to configure the Jenkins pipeline and then integrated my own scripts to automate the build flow.

Special thanks to Saurabh Joshi for his support in creating and setting up the pipeline for the project I’m currently working on.