--- description: Learn how to use environment variables, secrets, and reserved variables to configure your Capacitor and Ionic builds in Capawesome Cloud. title: Env Variables & Secrets in Capawesome Cloud - Capawesome image: https://capawesome.io/docs/assets/images/social/blog/using-environment-variables-and-secrets-in-capawesome-cloud-builds.png --- [ Skip to content](#using-environment-variables-and-secrets-in-capawesome-cloud-builds) [ 🔐 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 ](/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 or Yarn ](/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 * [ Default Variables ](#default-variables) * [ Common Use Cases ](#common-use-cases) * [ Why Environment Variables Matter ](#why-environment-variables-matter) * [ Try Capawesome Cloud ](#try-capawesome-cloud) * [ Conclusion ](#conclusion) # Using Environment Variables and Secrets in Capawesome Cloud Builds[¶](#using-environment-variables-and-secrets-in-capawesome-cloud-builds "Permanent link") When building mobile apps in the cloud, it's common to need different configuration values depending on the environment. A staging build might use a different API endpoint than a production build, or you might need to inject API keys that shouldn't be committed to your repository. With [Capawesome Cloud](/), you can define environments, add environment variables and secrets, and customize the build stack using reserved variables—all without changing your source code. [ ![Build and deploy your Capacitor app with Capawesome Cloud](../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](/) In this guide, you'll learn how to: * Create environments like staging and production * Add environment variables for configuration * Store sensitive values as secrets * Customize the build stack with reserved variables such as `NODE_VERSION` and `XCODE_VERSION` If you're new to Capawesome Cloud builds, you may want to first explore the [Native Builds](/docs/cloud/native-builds/) documentation. ## Create Environments[¶](#create-environments "Permanent link") Environments allow you to manage different configurations for your builds without changing your source code. For example, your staging build may connect to a staging API, while your production build connects to the live API. Typical environments include: * `development` * `staging` * `production` Each environment can have its own set of variables and secrets that are automatically injected during the build process. This makes it easy to keep build configurations organized and avoids manually changing values between builds. To create a custom environment, navigate to the [Environments](https://console.cloud.capawesome.io/apps/%5F/environments) page in the Capawesome Cloud Console. You can then select which environment to use when triggering a build. ## Add Environment Variables[¶](#add-environment-variables "Permanent link") Environment variables are ideal for non-sensitive configuration values. A common example is defining which API endpoint your app should use. To add a variable, navigate to the [Environments](https://console.cloud.capawesome.io/apps/%5F/environments) page, click on "Manage Variables" in the "Actions" menu of an environment, and create a new variable. You can configure different values for each environment, for example: | Environment | Variable | | ----------- | ---------------------------------------------- | | Staging | VITE\_API\_URL=https://staging-api.example.com | | Production | VITE\_API\_URL=https://api.example.com | During the cloud build, these variables become available to your build process. For example, in an application built with Vite: `` [](#%5F%5Fcodelineno-0-1)const apiUrl = import.meta.env.VITE_API_URL; [](#%5F%5Fcodelineno-0-2) [](#%5F%5Fcodelineno-0-3)fetch(`${apiUrl}/users`); `` When the production environment is selected, the build will automatically use the production API endpoint. The value is replaced during the build step and bundled into your application, so you can configure different environments without modifying your application code. Bulk Import You can bulk import multiple variables at once by using the "Import" feature in the actions menu. This allows you to paste in multiple `KEY=VALUE` pairs, making it easier to set up your environment. ## Store Sensitive Values as Secrets[¶](#store-sensitive-values-as-secrets "Permanent link") Some values should never appear in logs or configuration files. These should be stored as secrets. Secrets are encrypted at rest and in transit, and their values are never displayed in build logs. This makes them ideal for storing sensitive credentials such as API tokens, authentication credentials, deployment keys, and license keys. To add a secret, navigate to the [Environments](https://console.cloud.capawesome.io/apps/%5F/environments) page, click on "Manage Secrets" in the "Actions" menu of an environment, and create a new secret. Secrets are added the same way as regular variables, but their values remain hidden throughout the build process. For example, you might store a Sentry authentication token as a secret: `[](#%5F%5Fcodelineno-1-1)SENTRY_AUTH_TOKEN=your-secret-token ` This token could be used during the build to upload source maps: `[](#%5F%5Fcodelineno-2-1)npx sentry-cli releases new $CI_BUILD_ID [](#%5F%5Fcodelineno-2-2)npx sentry-cli releases files $CI_BUILD_ID upload-sourcemaps dist ` Because the value is stored as a secret, it will not appear in build logs. ## Customize the Build Stack with Reserved Variables[¶](#customize-the-build-stack-with-reserved-variables "Permanent link") Capawesome Cloud supports reserved variables that allow you to configure the build environment itself. These variables control which tools and versions are used during the build, and **they are added to an environment the same way as regular variables**. Let's see some examples. ### Selecting the Node.js Version[¶](#selecting-the-nodejs-version "Permanent link") If your project requires a specific Node.js version, you can configure it using the `NODE_VERSION` variable: `[](#%5F%5Fcodelineno-3-1)NODE_VERSION=22 ` During the build, Capawesome Cloud will automatically use that version. This is useful when your project depends on specific Node.js features or when you need to match your local development environment. ### Selecting the Xcode Version[¶](#selecting-the-xcode-version "Permanent link") For iOS builds, you can specify which version of Xcode should be used with the `XCODE_VERSION` variable: `[](#%5F%5Fcodelineno-4-1)XCODE_VERSION=16 ` This determines the iOS SDK, Swift version, and build tools used during compilation. This is particularly useful when Apple requires apps to be built with a newer SDK or when your project depends on a specific toolchain. For the complete list of reserved variables (including `JAVA_VERSION`, `IOS_SCHEME`, `ANDROID_FLAVOR`, and more), see the [Reserved Environment](/docs/cloud/native-builds/environment-variables/#reserved-variables) documentation. ## Default Variables[¶](#default-variables "Permanent link") During every build, Capawesome Cloud automatically provides default variables that give you information about the current build context. These include variables like `CI_BUILD_ID`, `CI_GIT_REFERENCE`, `CI_GIT_COMMIT_SHA`, and `CI_PLATFORM`. You can use these variables in your build scripts to make decisions based on the build context. For example, you might use `CI_BUILD_ID` to tag releases in your error monitoring tool, or use `CI_GIT_REFERENCE` to determine which branch triggered the build. `[](#%5F%5Fcodelineno-5-1)echo "Building from branch: $CI_GIT_REFERENCE" [](#%5F%5Fcodelineno-5-2)echo "Commit: $CI_GIT_COMMIT_SHA" ` For the complete list of default variables, see the [Default Environment](/docs/cloud/native-builds/environment-variables/#default-variables) documentation. Reserved Variable Names Variables such as `CI` and any variable starting with `CI_` are reserved and cannot be overridden. They are automatically managed by the build system. ## Common Use Cases[¶](#common-use-cases "Permanent link") Here are some practical examples of how teams use environment variables and secrets in their builds. These are just a few ideas—the possibilities are endless. ### Switching Payment Provider Environments[¶](#switching-payment-provider-environments "Permanent link") Payment providers like Stripe or PayPal typically offer sandbox environments for testing. You can use environment variables to switch between sandbox and live endpoints: | Environment | Variable | | ----------- | -------------------------------------------------- | | Staging | VITE\_STRIPE\_API\_URL=https://api.stripe.com/test | | Production | VITE\_STRIPE\_API\_URL=https://api.stripe.com | You can also store the API keys as secrets: | Environment | Secret | | ----------- | -------------------------------------- | | Staging | STRIPE\_PUBLISHABLE\_KEY=pk\_test\_... | | Production | STRIPE\_PUBLISHABLE\_KEY=pk\_live\_... | This ensures your staging builds never accidentally process real payments. ### Uploading Source Maps to Error Monitoring[¶](#uploading-source-maps-to-error-monitoring "Permanent link") When using error monitoring tools like Sentry, uploading source maps during the build makes stack traces readable. Store your authentication token as a secret and use default variables to tag releases: `[](#%5F%5Fcodelineno-6-1)npx sentry-cli releases new $CI_BUILD_ID [](#%5F%5Fcodelineno-6-2)npx sentry-cli releases files $CI_BUILD_ID upload-sourcemaps dist [](#%5F%5Fcodelineno-6-3)npx sentry-cli releases set-commits $CI_BUILD_ID --commit "repo@$CI_GIT_COMMIT_SHA" ` ### Feature Flags Per Environment[¶](#feature-flags-per-environment "Permanent link") Environment variables can control which features are enabled in each build: `[](#%5F%5Fcodelineno-7-1)VITE_ENABLE_ANALYTICS=true [](#%5F%5Fcodelineno-7-2)VITE_ENABLE_DEBUG_MODE=false ` In your application code: `[](#%5F%5Fcodelineno-8-1)if (import.meta.env.VITE_ENABLE_DEBUG_MODE === 'true') { [](#%5F%5Fcodelineno-8-2) console.log('Debug mode enabled'); [](#%5F%5Fcodelineno-8-3)} ` This allows you to enable experimental features in staging while keeping them disabled in production builds. ### Private npm Registry Access[¶](#private-npm-registry-access "Permanent link") If your project uses private npm packages, you can store the registry token as a secret and configure npm to use it during the build. See the [Private npm Registry](/docs/cloud/native-builds/npm-private-registry/) guide for details. ### Conditional Build Logic[¶](#conditional-build-logic "Permanent link") Use default variables to customize build behavior based on the target platform or branch: `[](#%5F%5Fcodelineno-9-1)if [ "$CI_PLATFORM" = "ios" ]; then [](#%5F%5Fcodelineno-9-2) echo "Running iOS-specific setup..." [](#%5F%5Fcodelineno-9-3)fi [](#%5F%5Fcodelineno-9-4) [](#%5F%5Fcodelineno-9-5)if [ "$CI_GIT_REFERENCE" = "main" ]; then [](#%5F%5Fcodelineno-9-6) echo "Production build detected" [](#%5F%5Fcodelineno-9-7)fi ` ## Why Environment Variables Matter[¶](#why-environment-variables-matter "Permanent link") Whether you're building with Ionic, Angular, React, or Vue, environment variables allow you to change how your app builds and behaves without modifying source code or committing environment-specific configuration to your repository. This provides several advantages: * **Safer deployments**: Sensitive values never appear in your codebase * **Flexible builds**: Easily switch between staging and production configurations * **Better collaboration**: Team members can work with different environments without conflicts * **Simpler CI/CD**: No complex scripts or YAML files to manage ## Try Capawesome Cloud[¶](#try-capawesome-cloud "Permanent link") Ready to simplify your mobile CI/CD workflow? Capawesome Cloud provides a powerful way to manage your build configuration and automate your deployment pipeline for Capacitor and Ionic apps. [Try Capawesome Cloud Free](/) ## Conclusion[¶](#conclusion "Permanent link") Environment variables and secrets make it easy to manage build configuration in Capawesome Cloud. By combining environments, variables, and reserved build settings, you can securely store sensitive values, configure builds for different environments, customize the build stack, and simplify your CI/CD workflow. For more details, check out the [Environments](/docs/cloud/native-builds/environments/) documentation. If you have any questions, join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). For the latest updates, subscribe to the [Capawesome newsletter](/newsletter/). June 8, 2026 Back to top