Environment variable groups

How to define and use environment variable groups

Variable groups

Environment variable groups allow you to define and store related sets of variables that are reusable in your codemagic.yaml workflows. A variable group tags a set of variables that can be imported together in a codemagic.yaml file. For example, you could define a staging group for variables related to your staging deployment and a production group for variables related to your production deployment. The variable names in staging and production groups can be identical, but the values will be set depending on which group is imported in the workflow. This allows you to reference variables in reusable scripts, but assign the actual values per workflow based on the imported group.

One or more variable groups can be imported into codemagic.yaml environment section. For example, variable groups named magic_values and other_values can be imported with the following syntax:

workflows:
  workflow-name:
    environment:
      groups:
        - magic_values
        - other_values

Variables defined in environment variable groups work exactly as Environment Variables. The value of a variable named API_TOKEN can be referenced in a workflow as $API_TOKEN. Variables defined with the Secret option will have values obfuscated in the Codemagic UI.

Storing sensitive values/files

Entering values in the Variable value input and marking the Secret checkbox will automatically encrypt those values. However, note that in order to store binary files as secret environment variables, you first need to base64-encode them locally. To use the files, you will have to decode them during the build.

Some commonly known binary files that need to be base64-encoded. e.g.

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

This can be done with the help of different OS-specific command line tools.

On macOS, running the following command base64-encodes the file and copies the result to the clipboard:

  cat your_file_name.extension | base64 | pbcopy

On Windows, the PowerShell command to base64-encode a file and copy it to the clipboard is:

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

On Linux machines, we recommend installing xclip:

sudo apt-get install xclip
cat your_file_name.extension | base64 | xclip -selection clipboard

After running these command lines, you can paste the automatically copied string into the Variable value input and check the Secret checkbox to store the value in encrypted form in Codemagic.

Finally, base64-decode it during build time in your scripts section using the following command:

echo $YOUR_ENVIRONMENT_VARIABLE | base64 --decode > /path/to/decode/to/your_file_name.extension

Global variables and secrets

Global variable groups can be defined on the team settings page (which you can navigate to for your team on the Teams page).

By default, variable groups defined here can be used in any codemagic.yaml workflow in any application of the team. It is possible to limit variable groups to specific applications by clicking the edit icon next to the group you wish to manage under Application access.

Application environment variables

Application variable groups can be defined in the application settings Environment Variables tab and can be used in any codemagic.yaml workflow in the application.

Here you’ll find some of the application environment groups and variables explained.

Example for Android builds

environment:
  groups:
    - keystore_credentials
    - google_play_credentials
    - other 

Add the above-mentioned group environment variables in Codemagic UI (either in Application/Team variables), don’t forget to click Secret to make sensitive data encrypted:

Example for iOS builds

environment:
  groups:
    - appstore_credentials
    - ios_config

Add the above-mentioned group environment variables in Codemagic UI (either in Application/Team variables), don’t forget to click Secret to make sensitive data encrypted:

For more information on iOS codesigning check here

To access a variable, add the $ symbol in front of its name.

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 variables defined in a scope of higher precedence can override those in a lower precedence with the same name. For example, if you have a global variable API_KEY with a value global that is also defined in an application variable with the value app, then the value app will be used.

If variables with the same name are defined and imported from different 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.