--- description: Customize native iOS and Android builds in Capawesome Cloud with environments — create environments, add variables and secrets, and use them in a build. title: Set Up Environments - Capawesome image: https://capawesome.io/docs/assets/images/social/cloud/native-builds/environments.png --- [ Skip to content](#set-up-environments) [ 🔐 Introducing the **Capacitor Vault** plugin — store secrets behind biometrics or a device passcode.](/blog/announcing-the-capacitor-vault-plugin/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * Set Up Environments [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories # Set Up Environments[¶](#set-up-environments "Permanent link") Environment variables let you customize your native builds by providing configuration values, secrets, and tool versions that are available during the build. Capawesome Cloud supports several kinds: * **Default variables** — automatically set for every build (e.g. `CI`, `CI_BUILD_NUMBER`). You can't override them. See the [Environment variables](/docs/cloud/native-builds/environment-variables/) reference. * **Reserved variables** — platform and tool configuration you set, such as `JAVA_VERSION` or `ANDROID_BUILD_TYPE`. See the [Environment variables](/docs/cloud/native-builds/environment-variables/) reference. * **Custom environments** — named sets of variables and secrets for different scenarios (development, staging, production). * **Ad-hoc variables** — temporary variables set when triggering a single build (not persisted). A custom environment is the usual starting point. The flow is the same whether you use the CLI or the Console: **create an environment, add variables and secrets, then select it when you build.** ## Create a custom environment[¶](#create-a-custom-environment "Permanent link") A custom environment is a reusable, named set of variables and secrets you can select when triggering a build — for example separate environments for development, staging, and production. CLIConsole Create an environment with the [apps:environments:create](/docs/cloud/cli/commands/#appsenvironmentscreate) command: `[](#%5F%5Fcodelineno-0-1)npx @capawesome/cli apps:environments:create --name production ` Open the [Environments](https://console.cloud.capawesome.io/apps/%5F/environments) page, click **Create Environment**, and give it a name. ## Add variables and secrets[¶](#add-variables-and-secrets "Permanent link") An environment holds two kinds of values: * **Variables** store non-sensitive configuration such as API endpoints, feature flags, or version numbers. * **Secrets** are encrypted values for sensitive data such as API keys, certificates, and passwords. They're encrypted at rest and in transit, and their values never appear in build logs. Both are accessed the same way in your build scripts, using standard environment-variable syntax. CLIConsole Add variables and secrets with the [apps:environments:set](/docs/cloud/cli/commands/#appsenvironmentsset) command. Pass `--variable` / `--secret` (repeatable), or import many at once from a `.env` file with `--variable-file` / `--secret-file`: `[](#%5F%5Fcodelineno-1-1)npx @capawesome/cli apps:environments:set \ [](#%5F%5Fcodelineno-1-2) --name production \ [](#%5F%5Fcodelineno-1-3) --variable API_URL=https://api.example.com \ [](#%5F%5Fcodelineno-1-4) --secret API_KEY=sk_live_... ` Remove values again with [apps:environments:unset](/docs/cloud/cli/commands/#appsenvironmentsunset). On the [Environments](https://console.cloud.capawesome.io/apps/%5F/environments) page, choose **Manage Variables** or **Manage Secrets** from the environment's actions menu, then add your values. Use **Delete** to remove one. Bulk import Use the **Import** feature to paste multiple `KEY=VALUE` pairs at once — the equivalent of the CLI's `--variable-file` / `--secret-file`. ## Use an environment in a build[¶](#use-an-environment-in-a-build "Permanent link") Environments are applied per build — you choose which one (if any) to use when you [trigger a build](/docs/cloud/native-builds/builds/). CLIConsole Pass `--environment` to [apps:builds:create](/docs/cloud/native-builds/builds/): `[](#%5F%5Fcodelineno-2-1)npx @capawesome/cli apps:builds:create --platform android --git-ref main --environment production ` In the **Build from Git** dialog, select your environment from the **Environment** dropdown before starting the build. ## Set a default environment[¶](#set-a-default-environment "Permanent link") You can set a default environment that is preselected for every new build — useful when an environment always applies (for example, it holds a license key for a private npm package). In the [Console](https://console.cloud.capawesome.io/), open your app's **Settings**, and in the **Builds** section enable the **Default Environment** toggle, select the environment, and save. ## Ad-hoc variables[¶](#ad-hoc-variables "Permanent link") Need a value for just one build? Pass it as an **ad-hoc variable** when you trigger the build, without creating an environment — handy for testing a different tool version or [overriding native configuration](/docs/cloud/native-builds/native-configurations/): `[](#%5F%5Fcodelineno-3-1)npx @capawesome/cli apps:builds:create --platform android --git-ref main --variable JAVA_VERSION=21 ` Ad-hoc variables are **not encrypted** and may appear in build logs, so don't use them for secrets. Reserved names The variable `CI` and any variable starting with `CI_` are reserved and cannot be overridden. Tool versions The available versions for Node.js, Java, and Xcode depend on your build stack — see [Build stacks](/docs/cloud/native-builds/build-stacks/). ## Bonus: Video Walkthrough[¶](#bonus-video-walkthrough "Permanent link") For a detailed walkthrough with examples, see the blog post [Using Environment Variables and Secrets in Capawesome Cloud Builds](/blog/using-environment-variables-and-secrets-in-capawesome-cloud-builds/). June 8, 2026 Back to top