Environment variables and variable groups

How to configure environment variables and groups in Codemagic

Environment variables are the recommended way to store configuration settings and sensitive data—such as credentials, configuration files, or API keys—needed for successful builds and integrations with external services. Sensitive information should never be committed to your Git repository. Instead, add it securely as environment variables in the Codemagic UI, where it can be accessed during workflows without being exposed in version control.

If you’re storing secrets in environment variables, you can enable an extra layer of security by marking the variable as Secure. This encrypts the variable and hides its value in the UI and build logs.

You can add environment variables and secrets on the app level or on the team level to make them available across team apps. Codemagic organizes user-defined environment variables into variable groups which you can import during the build, read more about it below.

Codemagic also provides a variety of built-in environment variables to streamline your workflows. You can check the full list here.

See an overview of how to work with environment variables in Codemagic in the video below.

Variable groups and accessing variables

All environment variables and secrets added in the Codemagic UI must be assigned a group. To make the variables available to the build machine, the variable group must be referenced in your codemagic.yaml workflow.

A variable group allows you to define and store related environment variables that can be imported together in a codemagic.yaml file. For instance, you might create separate staging and production groups, each containing variables with the same names but different values. By importing the appropriate group in your workflow, you can reuse the same script logic while dynamically applying environment-specific configurations.

Variable groups to be imported are listed in the environment section of codemagic.yaml. For example, variable groups named staging and production can be imported using the following syntax:

workflows:
  workflow-name:
    environment:
      groups:
        - staging
        - production

Variables defined in environment variable groups work exactly as all other environment variables. E.g., the value of a variable named API_TOKEN can be referenced in a workflow as $API_TOKEN.

App-level environment variables

The environment variables you add in application settings are accessible only to the application at hand.

1. Open your Codemagic app settings, and go to the Environment variables tab.
2. Enter the desired Variable name.
3. Enter the Variable value.
4. Enter the variable group name, e.g. appstore_credentials. Click the button to create the group.
5. If the Secure option is selected, the variable will be protected by encryption. Its value will not be visible in Codemagic UI or build logs, it will be transferred securely to the build machine and made available only while the build is running.
6. Click the Add button to add the variable.

Global variables and secrets

The Global variables and secrets section on the Teams page allows defining variable groups that can be made available to any application of the team.

It is possible to limit applications’ access to the variable group in variable group settings. Selecting All applications will grant all present and future apps access to the variable group. You can review application access settings anytime.

Marking a variable Secure will encrypt the variable and hide its value in the Codemagic UI and build logs. The variable will be transferred securely to the build machine and made available only while the build is running.

Bulk import of variables

To add many variables at once, click Add variables and select the option to import variables from a .env file. For each variable listed in the upload modal, you can choose to enable extra security by clicking the lock icon.

Storing binary files

In order to store binary files in environment variables, they first need to be base64 encoded locally. To use the files, you will have to decode them during the build.

Commonly used binary files that need to be base64 encoded include:

• Android keystore (.jks or .keystore)
• Provisioning profiles when manual code signing (.mobileprovision)
• iOS distribution certificate (.p12) when manual code signing.

The following examples show how to save a file named codemagic.keystore depending on your OS:

• Linux
• macOS
• Windows

sudo apt-get install xclip
cat codemagic.keystore | base64 | xclip -selection clipboard

openssl base64 -in codemagic.keystore

cat codemagic.keystore | base64 | pbcopy

[Convert]::ToBase64String([IO.File]::ReadAllBytes("codemagic.keystore")) | Set-Clipboard

After running these command lines, you can paste the automatically copied string into the Variable value field in Codemagic UI.

Using binary files during build

In order to use binary files during the build time, you need to base64 decode them and generate the file again. This can be performed with a simple echo command in a script.

workflows:
  workflow-name:
    environment:
    scripts:
      - name: Generate keystore file
        script: | 
          echo $YOUR_ENVIRONMENT_VARIABLE | base64 --decode > /path/to/decode/to/codemagic.keystore

Environment variable precedence

Environment variables with the same name and group from different sources will have the following precedence:

1. API variables
2. Application variables
3. Global variables

This means that variables defined in a scope of higher precedence will override variables defined in a lower scope if they have the same name.

If variables with the same name are defined and imported from different variable groups of the same level of precedence, the values from the last imported variable group will be used. For example, if two application variable groups magic and wand are defined each with a variable named magic_number and imported in a codemagic.yaml like so:

environment:
  groups:
    - magic
    - wand

Then the variable value in the group wand will be used.

Commonly used variable examples

Android builds

The following variable groups and variables are commonly used in Android builds. Add them in Codemagic UI (either as Application or as Team variables), make sure to click Secure to make sensitive data encrypted, and include the variable groups in your workflow.

    environment:
      groups:
        - keystore_credentials
        - google_play_credentials
        - other 

iOS builds

The following variable groups and variables are commonly used in iOS builds. Add them in Codemagic UI (either as Application or as Team variables), make sure to click Secure to make sensitive data encrypted, and include the variable groups in your workflow.

    environment:
      groups:
        - appstore_credentials
        - ios_config