Using Environment Variables and Secrets in Capawesome Cloud Builds¶

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

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 documentation.

Create Environments¶

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 page in the Capawesome Cloud Console. You can then select which environment to use when triggering a build.

Add Environment Variables¶

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 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:

const apiUrl = import.meta.env.VITE_API_URL;

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¶

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 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:

SENTRY_AUTH_TOKEN=your-secret-token

This token could be used during the build to upload source maps:

npx sentry-cli releases new $CI_BUILD_ID
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¶

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¶

If your project requires a specific Node.js version, you can configure it using the NODE_VERSION variable:

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¶

For iOS builds, you can specify which version of Xcode should be used with the XCODE_VERSION variable:

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 documentation.

Default Variables¶

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.

echo "Building from branch: $CI_GIT_REFERENCE"
echo "Commit: $CI_GIT_COMMIT_SHA"

For the complete list of default variables, see the Default Environment 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¶

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¶

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¶

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:

npx sentry-cli releases new $CI_BUILD_ID
npx sentry-cli releases files $CI_BUILD_ID upload-sourcemaps dist
npx sentry-cli releases set-commits $CI_BUILD_ID --commit "repo@$CI_GIT_COMMIT_SHA"

Feature Flags Per Environment¶

Environment variables can control which features are enabled in each build:

VITE_ENABLE_ANALYTICS=true
VITE_ENABLE_DEBUG_MODE=false

In your application code:

if (import.meta.env.VITE_ENABLE_DEBUG_MODE === 'true') {
  console.log('Debug mode enabled');
}

This allows you to enable experimental features in staging while keeping them disabled in production builds.

Private npm Registry Access¶

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 guide for details.

Conditional Build Logic¶

Use default variables to customize build behavior based on the target platform or branch:

if [ "$CI_PLATFORM" = "ios" ]; then
  echo "Running iOS-specific setup..."
fi

if [ "$CI_GIT_REFERENCE" = "main" ]; then
  echo "Production build detected"
fi

Why Environment Variables Matter¶

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¶

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¶

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 documentation.

If you have any questions, join the Capawesome Discord server. For the latest updates, subscribe to the Capawesome newsletter.