React Native reference
Android and iOS are available to eligible Cascade accounts for supported native project shapes. Commands, generated files, platform prerequisites and recovery. Choose a reference section.
Step-by-step React Native setup →8 reference sections
Install the executable named cascade and verify which CLI your PATH resolves.
Node 22+, Git and GitHub CLI are required locally. Local Android SDK/JDK and Xcode are unnecessary for setup; CI resolves the native toolchains separately.
node --version git --version gh --version
npm install -g cascadeci-cli cascade version cascade help
Use npx without a global install
Alternatively: npx cascadeci-cli init, after login. Prefix every CLI command; choose your platform lanes in the initialization step.
npx cascadeci-cli login npx cascadeci-cli init --lanes build_apk # Fill cascade.secrets.env for selected lanes first. npx cascadeci-cli match npx cascadeci-cli doctor
Expected outcome: cascade version reports 0.1.0 (npm CLI); help lists init, match and doctor.
Next: Authenticate with Cascade and GitHub.
Authorize Cascade and confirm GitHub repository access.
cascade login gh auth login gh auth status
Complete Cascade browser authorization on your own device. Without a browser on this machine use
cascade login --no-browserand open the displayed URL yourself. For an expired session, run login again; do not create another app. The npx route uses the same prefixed commands from Installation.Expected outcome: Cascade confirms login; gh auth status identifies your GitHub account.
Next: Open a supported Git repository root.
Check the session, app link, metadata, workflows and selected-lane inputs.
cascade doctor
Doctor verifies project and package-manager metadata, declared Node requirements, workflow integrity and selected GitHub inputs. Delivery lanes also check provider-status readiness; APK-only builds do not need it. Commit Podfile.lock before iOS CI. Fix named errors using Troubleshooting below; do not submit a store release just to clear status validation.
Expected outcome: Doctor reports selected platforms and ready configuration, or a stable error with recovery guidance.
Next: Commit reviewed operational files and push.
Separate committed configuration from local credentials.
- cascade.project.yaml — app binding and detected RN setup; commit.
- .github/workflows/cascade.yml — authenticated build bootstrap; commit.
- .github/workflows/cascade-refresh.yml — lifecycle companion; commit.
- cascade.secrets.env.example — empty template; commit.
- cascade.secrets.env — local only and gitignored (0600 on POSIX); never commit.
git check-ignore cascade.secrets.env git status --short
Only .gitignore is modified. Init creates only two workflows, cascade.project.yaml, cascade.secrets.env and cascade.secrets.env.example. It does not install dependencies or build. cascade.yml obtains the selected runtime steps from Cascade; it is not a standalone native build recipe. Existing RN and Flutter workflows need no regeneration.
Expected outcome: Five files exist and cascade.secrets.env is ignored; native/package files are unchanged.
Next: Supply only selected-lane credentials.
Fill the ignored local env file using its field comments, then configure selected inputs.
- Android APK: provide ANDROID_KEYSTORE, KEYSTORE_PASSWORD, KEY_PASSWORD and KEYSTORE_ALIAS for your existing signing key. Play service-account credentials are required only for Play delivery/status lanes.
- iOS: supply existing Match signing storage (MATCH_GIT_URL, MATCH_GIT_AUTH, MATCH_PASSWORD), IOS_TEAM_ID and separate App Store Connect API key ID, issuer ID and private key. The current iOS version/build path requires API credentials even for build_ios. Signing storage must already contain a valid certificate and profile for the app/team. Cascade does not provision them.
- Unselected platform fields may remain empty. Notification recipients are optional. Never paste signing or provider credentials into chat, support tickets or workflow YAML.
# Android-only setup: cascade match # If an iOS lane is selected, use this instead: cascade match --ios
ANDROID_KEYSTORE is base64-encoded .jks contents. The Apple .p8 input is the private-key contents, not an example placeholder. Follow the generated env comments; unselected platform fields may stay empty.
Match uploads relevant build/sign/upload inputs to GitHub Secrets. Delivery status credentials also use Cascade encrypted storage. Current iOS version/build lookup requires App Store Connect API credentials even for build_ios. match --ios prepares a readonly Matchfile using an existing repository, certificate, profile and explicit IOS_TEAM_ID; it does not provision them. Notification recipients are optional. Provider access validation is not a build.
Expected outcome: Match confirms selected GitHub credential groups; iOS preparation uses existing signing storage.
Next: Review delivery controls before any push.
APK, AAB, signing and automatic version/versionCode. Google Play internal, closed, open and production tracks use the shared rollout behavior. Select delivery lanes deliberately; a normal push executes the configured lanes.
build_apk requires existing Android signing inputs; test_android and release_android also require Play service-account access. Leave unselected platform credentials empty.
Native device archive, Match signing, IPA export, automatic version/build, TestFlight upload and App Store review submission are implemented. iOS runs on macOS CI; local Xcode is unnecessary for setup. App Store submission does not imply approval or automatic release.
Confirm the next push will execute only the actions you intend.
Open Dashboard → your App → App settings → delivery lane controls. Review Android and iOS separately. A normal RN push executes configured lanes; a tag cannot bypass disabled controls. Existing apps retain their enabled lanes unless you deliberately change them.
Older affected iOS-only build apps may need Standard artifact builds enabled manually; ordinary re-init preserves user controls. Leave Play, TestFlight and App Store delivery disabled for the first artifact build.
Expected outcome: For a first artifact run, Standard artifact builds is enabled and store-delivery controls are off.
Next: Validate with doctor.
Committed android/ and/or ios/ native projects, one app module/target and an unambiguous scheme. npm, Yarn and pnpm lockfiles are supported. Compatible Expo-native/prebuilt projects with committed native directories use the RN path. Expo-managed without native directories, arbitrary monorepos, ambiguous targets/modules and complex flavors or multi-scheme layouts are unsupported. Real qualification covers React Native 0.76.9; broader version compatibility is not yet claimed.
- CLI_AUTH / expired browser authorization
- Run cascade login again, finish authorization before it expires, then retry the original command. For the npx route, use the prefixed login command from Installation. Do not recreate the app.
- GITHUB_REQUIRED / GITHUB_WRITE_REQUIRED
- Run gh auth status and gh repo view from this repository. Check the remote, default branch, organization authorization and write/secrets permissions. Cascade login does not sign you into GitHub.
- APP_ROOT_REQUIRED / PROJECT_AMBIGUOUS
- Use the Git app root with committed native projects. Nested monorepo app paths and Expo-managed projects without native directories are unsupported; do not generate an empty workflow as a workaround.
- CREDENTIALS_MISSING / STATUS_NOT_READY
- Fill only the named selected-lane inputs, run match (with --ios for iOS preparation), then doctor. APK-only builds do not need provider-status setup. Delivery status validation can remain pending before a recorded upload; do not submit a store release merely to clear onboarding.
- WORKFLOW_TAMPERED / WORKFLOW_INVALID
- Restore the exact issued workflows from your last known-good commit before retrying init or doctor. Do not hand-edit checksums or repeatedly regenerate an unchanged workflow.
- FEATURE_DISABLED / RN_PLATFORM_DISABLED / no run
- Check Standard artifact builds and your selected controls in App settings. Operator platform switches require Cascade support, not regenerated workflows. Confirm Actions is enabled, workflows were committed, the default branch matches the binding and the push reached that branch.
- SECRETS_TRACKED / CONFIG_CHANGED
- For a tracked local env file, remove it from the Git index and rotate any exposed credentials before retrying. For a genuine native metadata or repository configuration change, review it and rerun init deliberately; keep existing secrets and bindings.
Confirm the actual first build result instead of inferring success from setup.
Open the repository Actions tab and the linked app in the Release Control Center. Build / Release Action links to the exact run; Status Refresh Action is separate. Inspect available artifacts and stage diagnostics. Retained APK links expire; do not assume every artifact is hosted by Cascade.
For failures report the job ID and safe error code, then inspect Actions logs. Never send credentials or full provider responses. Built, uploaded, processing and available are different outcomes.
Open the React Native reference →Expected outcome: The exact Actions run shows its build result; Cascade records the corresponding execution outcome.
Next: Keep build-only lanes until the real build is verified; use reference and troubleshooting for failures.
Support matrix
- Flutter
- Android: Available. iOS: Available through the existing Dart CLI.
- React Native
- Android: Available. iOS: Available for supported native projects.
- Native Android/Kotlin and Native iOS/Swift
- Coming.
- Expo-managed without native directories
- Not supported; no EAS Build integration.