Migration of NativeScript Cloud Builds to Circle CI

In recent months we have re-evaluated our cloud build offering and the user demand for it. The results show there are a lot of missing features and people often struggle in scenarios where they need control of the environment or when an issue in a cloud operation occurs. Each of the cases are unique, but due to the architecture of the NativeScript cloud builds, we are not able to provide the experience our customers deserve.

We have researched different options for filling the gap between customers' requirements and our current architecture. We came to the conclusion that we need an entirely new solution. We have worked hard to provide it and we have already introduced it - cloud builds with Circle CI. You can read more about the solution in this great blog post from Dimitar Tachev.

The new solution provides much better experience in the terms of:

• Control of the environment
• CI integration (the new solution allows easy setup of CI for each of your PRs, which was almost impossible with existing cloud builds)
• Resolving issues and debugging them in the cloud
• Extensibilty of the cloud providers - the plugin can be tuned to use different cloud providers or even a local machine

IMPORTANT: As we do not see any benefit in keeping the existing cloud build solution when we have a much better one, we have decided to discontinue the existing NativeScript cloud builds. The stoppage will be effective on May 31st 2020 for all cloud builds.

What does it mean for you and your applications

Existing NativeScript cloud builds will be stopped effectively on May 31st 2020.

We encourage all of you to migrate to the new solution before this date!

How to migrate

Below we will try to provide a detailed description of how to migrate your existing application to be build with the nativescript-remote-builds plugin instead of NativeScript cloud builds.

System requirements

Before starting, please ensure you have installed all of the components listed below and they are accessible in your command line:

• OpenSSL - try openssl in your command line
• Ruby - execute ruby -v in your command line to ensure it is accessible
• Git - execute git --version in your command line to ensure it is accessible
• Fastlane - after you've installed Ruby, just execute gem install fastlane (you need version 2.144 or newer)

Preparing code signing for iOS

In case you want to build for Android, just go to Migrating the application

The setup of the current NativeScript cloud builds requires you to have a valid paid Apple developer account and a generated pair of certificate and provisioning profile.

The nativescript-remote-builds plugin works with fastlane behind the scenes and relies on the fastlane match approach for iOS code signing. In this approach fastlane manages your certificates and provisioning profiles and stores them in the private GitHub repository you've provided for this action.

Generating the fastlane match repository

1. First of all, you'll need Ruby installed on your machine. You can get it here.
2. After that, you need fastlane, just execute gem install fastlane
3. At this point you have two options: 3.1 In case you have macOS, we strongly recommend using the command fastlane match - the command will prompt you for the private repository to store the autogenerated certificates and provisions, your Apple identifier, and password. 3.2 In case you do not have macOS, you'll have to manually import the required certificates and provisions for building your applications. In this case use the fastlane match import command.

The two approaches are described below:

NOTE: When fastlane asks you for private match repository, ensure you are using ssh, not https

Migration with automatic codesigning (recommended way)

In this scenario you should not think about your current certificates and provisioning profiles. Just execute this on macOS:

fastlane match

The command will prompt you for your Apple credentials, the private repository for storing the certificates, and the password to protect the files. After you've entered all of the information, fastlane will automatically import all of the required certificates based on your Apple account and will use them from there during build.

NOTE: You will need macOS only the first time when you execute fastlane match. After that you will be able to build for iOS from Windows, Linux, and macOS.

Migration with manual codesigning (not the recommended way)

In case you do not want to use the automatic managing of provisions and certificates, you can import the certificate and the provisioning profile manually in the match repository. To achieve this you need the .mobileprovision, .p12, and .cer files used for building your application.

openssl pkcs12 -info -in <path to your .p12 certificate>

openssl pkcs12 -info -in ios_development.p12
Enter Import Password:
MAC: sha1, Iteration 1
MAC length: 20, salt length: 8
PKCS7 Encrypted data: pbeWithSHA1And40BitRC2-CBC, Iteration 2048
Certificate bag
Bag Attributes
    friendlyName: iPhone Developer: John Doe (F34A23801A)
    localKeyID: ...
subject=UID = KHMY4SS8C9, CN = iPhone Developer: John Doe (F34A23801A), OU = A49FBB0MS7, O = Company Name, C = US

issuer=C = US, O = Apple Inc., OU = Apple Worldwide Developer Relations, CN = Apple Worldwide Developer Relations Certification Authority

-----BEGIN CERTIFICATE-----
...

openssl pkcs12 -in <path to your .p12 certificate> -nodes | openssl x509 -noout -enddate

RemoveP12Password /Users/vladimirov/my-certificate.p12 123456 /Users/vladimirov/my-certificate-no-pass.p12

fastlane match import

Migrating the application

In order to migrate the application, you have to set up the nativescript-remote-builds plugin in your app. Here are the basic steps you need to take, more detailed description and all of the supported scenarios can be found in the plugins README.md:

1) Create your account in Circle CI or log in with your existing account.

2) Generate a personal access token for your Circle CI account and copy its value.

3) In your application install the nativescript-remote-builds plugin: npm install --save nativescript-remote-builds

4) Create .nsremote.config.json file at the root of your application.

5) Add the sshRepositoryUrl property in the .nsremote.config.json - the repository is the one associated with your application and enabled for builds in CircleCI:

{
    "circleci": {
        "sshRepositoryURL": "{{an SSH GitHub repository url}}"
    }
}

6) Ensure you have a valid ssh key without password on your local machine and associated with your GitHub account. You can follow steps here

7) Add your ssh key to your Circle CI account as shown in the following image.

NOTE: When setting the ssh key in Circle CI, you have to fill in hostname, ensure it is github.com

8) Create .nsremote.env.json file at the root of your application.

9) Add the Circle CI access token value in the .nsremote.env.json configuration file:

{
    "local": {
        "CIRCLE_CI_API_ACCESS_TOKEN": "{{your Circle CI access token generated in step 2}}"
    }
}

10) (required for iOS Builds) Add IOS_SIGNING_REPO_URL, IOS_APPLE_ID and MATCH_PASSWORD to the .nsremote.env.json file:

{
    "local": {
        "CIRCLE_CI_API_ACCESS_TOKEN": "{{your Circle CI access token generated in step 2}}"
    },
    "remote": {
        "IOS_SIGNING_REPO_URL": "{{ssh url to the repository containing your certificates (the fastlane match repository)}}",
        "IOS_APPLE_ID": "{{the email with which you login in the Apple developer portal}}",
        "MATCH_PASSWORD": "{{the password for your fastlane match repository}}"
    }
}

11) Build in the cloud with Circle CI by using:

tns build ios|android

You can even run it directly if you have connected devices:

tns run

Or even debug on specific device/emulator:

tns debug ios|android

Whenever NativeScript CLI needs to build the application, it will do it in the Circle CI. During the build you will see message from the CLI:

A cloud build has started. Open <url> for more details.

You can check the URL in Circle CI for details of the execution.

Summary

The new solution for NativeScript cloud builds is much more flexible and powerful. We encourage you to give it a try and get the most out of it!