Skip to main content

Build Environments

Introduction​

Environments give you a way to customize the build process for your application in order to produce different versions of your applications for different environments from the same codebase. All environment variables are accessible to any build scripts that run during the npm run install and npm run build portion of your builds.

There are three types of Environment variables available to use:

Predefined Environments​

Every time a build occurs, it's done in a secure environment with predefined key/value pair variables made available and accessible with process.env.MY_VAR syntax in NodeJS or $MY_VAR syntax in a standard shell script. These variables can be leveraged to customize the build and outputs.

The following environment variables are provided in every build and can be accessed in build scripts:

  • CI_APP_ID (string): Your Ionic app's unique ID.
  • CI_APP_NAME (string): Your Ionic app's name.
  • CI_AUTOMATED_BUILD (int): Whether this build occurred as a result of an automation (0 for false, 1 for true).
  • CI_AUTOMATION_ID (optional int): The unique ID of the automation which created this build.
  • CI_AUTOMATION_NAME (optional string): The name of the automation which created this build.
  • CI_BUILD_ID (int): The globally unique ID of this build.
  • CI_BUILD_NUMBER (int): The sequential build number.
  • CI_GIT_COMMIT_SHA (string): The SHA for the commit on which the build was run.
  • CI_GIT_COMMIT_MSG (string): The message for the commit on which the build was run.
  • CI_GIT_REF (string): The git ref from which the build was created (i.e. main).
  • CI_GIT_REF_TYPE (string): The git ref type (i.e. branch).
  • CI_PLATFORM (string): The platform for the build (ios, android, web).
  • APP_PREVIEW_HASH (optional string): The unique hash used in the shared Web Preview URL if enabled for build.

Usage​

For example, you could replace your build script in the package.json with a custom shell script that reads the branch and triggers a custom build.

// customize the build script in the package.json
{
...
    "scripts": {
        "build": "./mybuild.sh",
    },
...
#!/bin/bash
if [ "$CI_GIT_REF" = "main" ]; then
    npx ionic build --prod
else
    npx ionic build
fi

Custom Environments​

In addition to the predefined environments, you can create custom environments. Custom environments make it easy to create and manage custom sets of key/value pairs to further customize builds on Ionic Appflow. Common use cases include customizing your build process to build versions of your app that connect to different APIs, or to build different white labeled versions of your application.

To get started with custom environments, open the app you wish to work on and navigate in the sidebar to Build > Environments, then click New Environment on the top right. You should see a form like this:

Create Environment Form

There are two environment variables sections:

  • Secrets
  • Variables

Secrets are hidden and never shown in the dashboard after they have been added, while the variables are always available to be read.

The environments dashboard also lists available custom environments along with their configured key/value pairs and secrets keys.

Environments List View

System Overrides​

To override some of the build tools used in the Appflow Build Stacks, specify the following keys in the Variables section of a custom environment:

Always refer to the Build Stacks page for the most recent values.

Additionally, to access private git repositories, add a secret inside an environment with key GIT_CREDENTIALS and for the value, follow the URL format specified here.

iOS and Android Projects​

Use custom environments to override automatic iOS scheme detection or Android build variants. Learn more here.

  • iOS scheme: IOS_SCHEME with a value such as MyScheme.
  • Android build type: ANDROID_BUILD_TYPE with a value such as Staging.
  • Android product flavor: ANDROID_FLAVOR with a value such as Demo.

Ad-hoc Environments​

You can also define environment variables that will apply to a specific build. These variables will not persist across builds, but are helpful when troubleshooting builds or testing out new build settings.

Note the following when using ad-hoc environments:

  • If you configure both a Custom Environment and define ad-hoc environment variables for a build, all environment variables will be applied to that build.
  • If you define an ad-hoc environment variable with the same name as a variable in a Custom Environment, the ad-hoc environment variables value will be the one applied to the build.
  • For sensitive data, use secrets in a Custom Environment.

Ad-hoc Environments

Contents