Developer guides
How to use Cascade
Set up a supported React Native project, configure only the inputs you need and follow your first CI build. Choose a step below.
React Native
Android and iOS are available to eligible Cascade accounts for supported native project shapes. Account → install → authenticate → init → credentials → controls → doctor → first build. Expand each step.
React Native reference →10 setup steps
Create the account that will own or access this app.
- Open Create an account.
- Choose Solo or Organization, verify your email and complete workspace prompts.
- Existing users can sign in with their normal account.
Expected outcome: You can sign in and open your workspace.
Next: Install the npm CLI.
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.
Link the intended app and bind its GitHub default branch.
Use the Git app root with package.json and committed android/ and/or ios/ projects. Create the GitHub repository, push an initial commit and confirm its default branch. You need repository write access, Actions secrets permissions and Actions enabled.
gh repo view git rev-parse --show-toplevel
Commit your npm, Yarn or pnpm lockfile, Android Gradle wrapper, ios/Podfile.lock when using CocoaPods, and Gemfile.lock when using Bundler. Resolve ambiguous native targets and shared schemes before setup.
Choose exactly one command:
Android only — signed APK; no Google Play credentials required.
cascade init --lanes build_apk
iOS only — signed IPA; existing Apple signing and API access required.
cascade init --lanes build_ios
Android + iOS — configure each platform independently.
cascade init --lanes build_apk,build_ios
Init creates or links an app. Use --app ID or --pick for intentional existing-app selection; --new deliberately creates another app. Do not use --rebind to fix authentication. An unchanged second init retains the binding and workflows.
Expected outcome: Init reports the detected metadata, app link and generated workflows.
Next: Review the five generated files.
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.
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.
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.
Review Git status, then commit configuration without local secrets.
git check-ignore cascade.secrets.env git status --short git add .gitignore cascade.project.yaml cascade.secrets.env.example .github/workflows/cascade.yml .github/workflows/cascade-refresh.yml git commit -m "First RN CI build" git push
Also commit ios/fastlane/Matchfile if match --ios created it. Push to the default branch recorded at init; another branch or a pull request is not the normal release trigger. No run? Check Actions permissions, committed workflows, the bound branch and lane controls. Do not regenerate unchanged workflows.
Expected outcome: GitHub Actions starts the bound Cascade workflow after a default-branch push.
Next: Inspect the exact Actions run and artifact.
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.
Troubleshooting
- 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.
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.
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.