--- title: Set Up Environments description: Customize native iOS and Android builds in Capawesome Cloud with environments — create environments, add variables and secrets, and use them in a build. --- # Set Up Environments 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](environment-variables.md) reference. - **Reserved variables** — platform and tool configuration you set, such as `JAVA_VERSION` or `ANDROID_BUILD_TYPE`. See the [Environment variables](environment-variables.md) 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 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. === "CLI" Create an environment with the [`apps:environments:create`](../cli/commands.md#appsenvironmentscreate) command: ```bash npx @capawesome/cli apps:environments:create --name production ``` === "Console" Open the [Environments](https://console.cloud.capawesome.io/apps/_/environments){:target="_blank"} page, click **Create environment**, and give it a name. ## Add variables and secrets 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. === "CLI" Add variables and secrets with the [`apps:environments:set`](../cli/commands.md#appsenvironmentsset) command. Pass `--variable` / `--secret` (repeatable), or import many at once from a `.env` file with `--variable-file` / `--secret-file`: ```bash npx @capawesome/cli apps:environments:set \ --name production \ --variable API_URL=https://api.example.com \ --secret API_KEY=sk_live_... ``` Remove values again with [`apps:environments:unset`](../cli/commands.md#appsenvironmentsunset). === "Console" On the [Environments](https://console.cloud.capawesome.io/apps/_/environments){:target="_blank"} page, choose **Manage environment variables** or **Manage environment secrets** from the environment's actions menu, then add your values. Use **Delete** to remove one. !!! tip "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 Environments are applied per build — you choose which one (if any) to use when you [trigger a build](builds.md). === "CLI" Pass `--environment` to [`apps:builds:create`](builds.md): ```bash npx @capawesome/cli apps:builds:create --platform android --git-ref main --environment production ``` === "Console" In the **Build from Git** dialog, select your environment from the **Environment** dropdown before starting the build. ## Set a default environment 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/){:target="_blank"}, open your app's **Settings**, and in the **Builds** section enable the **Default environment** toggle, select the environment, and save. ## Ad-hoc variables 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 [overwriting native project settings with Trapeze](native-configurations.md#advanced-trapeze): ```bash 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. !!! warning "Reserved names" The variable `CI` and any variable starting with `CI_` are reserved and cannot be overridden. !!! note "Tool versions" The available versions for Node.js, Java, and Xcode depend on your build stack — see [Build stacks](build-stacks.md). ## Bonus: Video Walkthrough For a detailed walkthrough with examples, see the blog post [Using Environment Variables and Secrets in Capawesome Cloud Builds](../../blog/posts/using-environment-variables-and-secrets-in-capawesome-cloud-builds.md).