Adding environment variables in codemagic.yaml

How to configure environment variables and groups


Configuring Environment variables

Environment variables are useful for storing various pieces of data and making it available during build time. Typical use cases include credentials, configuration files or API keys that are required for successful building or integration with external services. Besides user defined environment variables, Codemagic also provides numerous useful variables already built-in. You can check the full list here..

  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. The whole build machine will be destroyed after build ends.
  6. Click the Add button to add the variable.

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 all other environment variables. E.g., 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 binary files

In order to store binary files as 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:

For Linux machines, we recommend installing xclip:

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

Alternatively, you can run the following command and carefuly copy/paste the output:

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

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

cat codemagic.keystore | base64 | pbcopy

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

[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.

Tip: A convenient way to check if a file is binary is to try to peek into the file using less filename.extension. If it is binary, you’ll be asked “filename maybe is a binary file. See it anyway?

Using binary files

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

Global variables and secrets

Variable groups can also be defined on the Teams page for both teams and personal accounts. Variable groups defined here are global and can be used in any codemagic.yaml workflow and 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.

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.

Variable nameVariable valueGroup
CM_KEYSTORE_PATH/tmp/keystore.keystorekeystore_credentials
CM_KEYSTOREcontents of keystore - base64 encodedkeystore_credentials
CM_KEYSTORE_PASSWORDPut your keystore password herekeystore_credentials
CM_KEY_PASSWORDPut your key alias password herekeystore_credentials
CM_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
    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.

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 hereappstore_credentials
BUNDLE_IDPut your bundle id hereios_config
APP_STORE_IDPut your TestFlight Apple id number (General > App Information > Apple ID)ios_config
XCODE_WORKSPACEPut the name of your workspace hereios_config
XCODE_SCHEMEPut the name of your scheme hereios_config
    environment:
      groups:
        - appstore_credentials
        - ios_config