How to Use Appdome Build-2secure Orb for CircleCI

Last updated March 9, 2023 by Appdome

This Knowledge Base article provides instructions on how to create and use Appdome build-2secure orb ; namely, a reusable snippet of code that helps automate repetitive processes, speed up project setup, and facilitate integration with third-party tools. With this orb, you can easily secure and customize your mobile apps on CircleCI, including signing your app with your own enterprise certificate for added flexibility and control. No coding or technical expertise is required.


To successfully create and use Appdome Build-2secure in CircleCI environment, you need to have the following:

    • The setting Allow Uncertified Orbs is enabled in CircleCI.

To allow using uncertified orbs in CircleCI:

      1. From the menu on the left, go to Organization Settings > Security.
      2. Within the Orb Security Settings > Allow Uncertified Orbs section, select the option Yes as shown below.
        Orb Security Settings

Building the App by Using Appdome Build-2secure Orb

To build the app:

  1. Edit your .circleci/config.yml favorite IDE or with the CircleCI in-app configuration editor.

    1. Ensure that the CircleCI version, which is displayed at the top of your .circleci/config.yml, is 2.1.
      version: 2.1
    2. Add the orbs block (stanza) below your version and install Appdome Build-2secure in CircleCI by adding the following to your .circleci/config.yml, where X.Y.Z represents the version number; for example, 2.3.1.
        build-2secure: appdome/build-2secure@X.Y.Z

      Alternatively, set version to volatile to get the latest version.

        build-2secure: appdome/build-2secure@volatile
    3. In order to use Appdome build-2secure orb, it’s necessary to obtain the Appdome-provided API token by copying it, as described in this article, Then add it as an environment variable in CircleCI. To do so, navigate to the Project Settings section on CircleCI’s platform.
      Project Settings button in Circle CI
    4. From the menu on the left, click Environment Variables and then click Add Environment Variable.
      Add Environment Variables
    5. Use the App Environment Variable dialog box to add the Appdome API key variable by entering the following values:
      Add API Key as env. variable
    6. In addition to your APPDOME_API_TOKEN, you have to insert your iOS or Android fusion-set-id to CircleCI’s Environment Variables:
      1. For iOS apps, add the following variables:
        Name: FUSION_SET_ID_IOS
        Value: <Appdome_Fusion_Set_ID_For_iOS>
      2. For Android apps, add the following variables:
        Value: <Appdome_Fusion_Set_ID_For_Android>
    7. Add Appdome Build-2secure to your job by calling it from the jobs block of your .circleci/config.yml file, as shown in the base template below.
      For additional usage examples, see Appdome page on CircleCI website.

          Appdome fusion:
              - build-2secure/appdome_runner:
                    runner: <type_of_run>
                    team-id: <your_team_ID> - remove this line when working on personal workspace.
                    appFile: <remote_app_location_of_the_non-protected_app>
                    output: <secured_app_file_name>
                    sign-overrides: <path_to_remote_JSON_download_file_location>
                    google-play-signing: <true_or_false> - (For Android only!).
    8. In the code block above, set the following variables with the parameter values as described below:
      1. runner
        Any of the following options, in accordance with the build platform you need and the sign type:

      2. team-id
        Insert your team-id. This line is optional and may be removed when working on a personal workspace.
      3. appFile
        Please provide the remote address of the non-protected application. For example, “https://[URL_of_your_non_protected_app]”.
      4. output
        The requested name of the secured application.
      5. sign-overrides
        Include this parameter with the path to a JSON file, only if you want to override signing with a custom JSON file. Otherwise, remove this line.
      6. google-play-signing
        For Android only. Either leave the default value False or, if you use Google Play App Signing to allow developers to offload the signing of their release APKs onto Google, change the value to True.
    9. For each type of sign, you have to add the following environment variables as explained above.


      Certain sign options require  files. To accomplish this, file must first be encoded by using the base64 method, and the output of this process must be stored within the specified environment variable, as described in section “Adding Files as Environment Variables Using Base64 Encoding” below.

          • Name:  KEYSTORE_FILE
            Value: <Keystore_base64_File>
          • Name:  KEYSTORE_PASSWORD
            Value: <Your_Keystore_Password>
          • Name:  KEYSTORE_ALIAS
            Value: <Your_Keystore_Alias_Name>
          • Name:  KEYSTORE_KEY_PASSWORD
            Value: <Your_Keystore_Key_Password>
          • Name:  SIGN_FINGERPRINT
            Value:  <Your_SHA1_Fingerprint>
          • Name:  SIGN_FINGERPRINT
            Value:  <Your_SHA1_Fingerprint>
          • Name:  KEYSTORE_P12_FILE
            Value: <P12_Keystore_base64_File>
          • Name:  P12_PASSWORD
            Value: <Your_P12_Keystore_Password>
            Value: <Mobile_Provision_profile_base64_file>
          • Name:  ENTITLEMENTS_FILE
            Value: <Entitlement_base64_file>
            Value: <Mobile_Provision_profile_base64_file>
            Value: <Mobile_Provision_profile_base64_file>
          • Name:  ENTITLEMENTS_FILE
            Value: <Entitlement_base64_file>

10. Run your CircleCI job.
Appdome Build-2secure automatically integrates the requested security features into your app.
you can trigger the build by the following trigger options.

11. After the build is complete, you can download the secured app from the Artifacts tab in the CircleCI platform.
The following artifacts will be available for download:

Artifacts available for download

The name of the secured output app will match the name selected in the output parameter.

Adding Files as Environment Variables by Using Base64 Encoding

To add files as environment variables:

  1. Open a terminal.
  2. Encode the requested file with base64, and save (paste) it in a temporary text file:
    Usage:	base64 [-i in_file] [-o out_file]

    For example:

    base64 -i appdome.keystore -o example_temp.txt
  3. Copy the contents of the text file into the matching environment variable as shown in the images below.
    Copy text to environment variableAdd environment variable filled



let's solve it together

KarenMaking your security project a success!
By filling out this form, you opt-in to recieve emails from us.