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.

Prerequisites

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

- An Appdome account
  - Appdome’s token
  - Fusion-Set ID
- A CircleCI account. To create a new project on CircleCI, please follow this guide.

- The setting Allow Uncertified Orbs is enabled in CircleCI.

To allow using uncertified orbs in CircleCI:

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

Building the App by Using Appdome Build-2secure Orb

To build the app:

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.
```
orbs:
  build-2secure: appdome/build-2secure@X.Y.Z
```
  Alternatively, set version to volatile to get the latest version.
```
orbs:
  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.
4. From the menu on the left, click Environment Variables and then click Add Environment Variable.
5. Use the App Environment Variable dialog box to add the Appdome API key variable by entering the following values:
  Name: APPDOME_API_TOKEN
  Value: <YOUR_APPDOME_TOKEN>
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:
    Name: FUSION_SET_ID_ANDROID
    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.
```
  workflows:
    Appdome fusion:
      jobs:
        - 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:
    - ANDROID_AUTO_SIGNING
      For more information follow the instructions in this Knowledge Base article.
    - ANDROID_PRIVATE_SIGNING – for more information follow the instructions in this Knowledge Base article.
    - ANDROID_AUTO_DEV_SIGNING – for more information follow the instructions in this Knowledge Base article.
    - IOS_AUTO_SIGNING – for more information follow the instructions in this Knowledge Base article.
    - IOS_PRIVATE_SIGNING – for more information follow the instructions in this Knowledge Base article.
    - IOS_AUTO_DEV_SIGNING – for more information follow the instructions in this Knowledge Base article.
  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.
  
  Note:
  
  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.
- - - ANDROID_AUTO_SIGNING
      - 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>
    - ANDROID_PRIVATE_SIGNING
      - Name: SIGN_FINGERPRINT
        Value: <Your_SHA1_Fingerprint>
    - ANDROID_AUTO_DEV_SIGNING
      - Name: SIGN_FINGERPRINT
        Value: <Your_SHA1_Fingerprint>
    - IOS_AUTO_SIGNING
      - Name: KEYSTORE_P12_FILE
        Value: <P12_Keystore_base64_File>
      - Name: P12_PASSWORD
        Value: <Your_P12_Keystore_Password>
      - Name: MOBILE_PROVISION_PROFILE_FILE
        Value: <Mobile_Provision_profile_base64_file>
      - Name: ENTITLEMENTS_FILE
        Value: <Entitlement_base64_file>
    - IOS_PRIVATE_SIGNING
      - Name: MOBILE_PROVISION_PROFILE_FILE
        Value: <Mobile_Provision_profile_base64_file>
    - IOS_AUTO_DEV_SIGNING
      - Name: MOBILE_PROVISION_PROFILE_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:

Open a terminal.
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
```
Copy the contents of the text file into the matching environment variable as shown in the images below.