Environment variable groups

How to define and use environment variable groups

You can add environment variables in the following places:

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 secure option will have values obfuscated in the Codemagic UI.

Storing sensitive values/files

Entering values in the Variable value input and marking the Secure checkbox will automatically encrypt those values. However, note that in order to store binary files as secure environment variables, first it needs to be base64 encoded 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 manual code signing (.mobileprovision)
  • iOS distribution certificate (.p12) when manual code signing.

This can be done with the help of different OS-specific command lines':

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

cat your_file_name.extension | base64 | pbcopy

For 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

For Linux machines, we recommend installing xclip:

sudo apt-get install xclip
cat your_file_name.extension | base64 | xclip -selection clipboard
Tip: A convenient way to find a binary file is to try to peek into the file using less filename.extension. You’ll be asked “filename maybe is a binary file. See it anyway?

After running these command lines, you can paste the automatically copied string into the Variable value input and check the Secure 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

Tip: When copying file contents always include any tags. e.g. Don’t forget to copy -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- too.

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.

Global variable groups are only available for Teams. You can read more about teams here.

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 Secure to make sensitive data encrypted:

Variable nameVariable valueGroup
FCI_KEY_ALIAS/tmp/keystore.keystorekeystore_credentials
FCI_KEYSTOREcontents of keystore - base64 encodedkeystore_credentials
FCI_KEYSTORE_PASSWORDPut your keystore password herekeystore_credentials
FCI_KEY_PASSWORDPut your key alias password herekeystore_credentials
FCI_KEY_ALIASPut your key alias herekeystore_credentials
GCLOUD_SERVICE_ACCOUNT_CREDENTIALSPut your Google Play service account credentials heregoogle_play_credentials
GOOGLE_PLAY_TRACKAny default or custom track that is not in ‘draft’ statusgoogle_play_credentials
PACKAGE_NAMEPut your package name hereother

Example for iOS builds

environment:
  groups:
    - appstore_credentials
    - certificate_credentials
    - other

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

Variable nameVariable valueGroup
APP_STORE_CONNECT_ISSUER_IDPut your App Store Connect Issuer Id hereappstore_credentials
APP_STORE_CONNECT_KEY_IDENTIFIERPut your App Store Connect Key Identifier hereappstore_credentials
APP_STORE_CONNECT_PRIVATE_KEYPut your App Store Connect Private Key hereappstore_credentials
CERTIFICATE_PRIVATE_KEYPut your Certificate Private Key herecertificate_credentials
BUNDLE_IDPut your bundle id hereother
APP_STORE_IDPut your TestFlight Apple id number (General > App Information > Apple ID)other
XCODE_WORKSPACEPut the name of your workspace hereother
XCODE_SCHEMEPut the name of your scheme hereother

For more information on iOS codesigning check here

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

Tip: If the group of variables is reusable among various applications, they can be defined in Global variables and secrets in Team settings for easier access.

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.