Skip to content

Latest commit

 

History

History
134 lines (86 loc) · 7.84 KB

CIRCLECI.md

File metadata and controls

134 lines (86 loc) · 7.84 KB

NativeScript remote builds with Circle CI

The Circle CI remote enables Fastlane based remote builds in CircleCI virtual machines.

Prerequisites

  • NativeScript 6.4.0 or higher.
  • A CircleCI account as this remote is based on Circle CI virtual machines.

NOTE: If you are building an open source app, you could apply for free CircleCI iOS builds.

  • A Personal API Token for your Circle CI account (you have to be logged-in in Circle CI in order to see this page). It will be used for the communication between your local machined and the Circle CI services for managing environment variables and getting the read status.

NOTE: You have to be logged-in in Circle CI in order to see the Circle CI Personal API Tokens page,

Basic Setup

In order to get started with Circle CI based builds, you need a GitHub repository for syncing your local app state with the Circle CI virtual machines. In this repository, the plugin will create a temporary branch for each build operation named circle-ci{{uniqueBuildId}} and will not affect the existing branches. The repository could be either the app repository itself or any other GitHub repository and should be specified in the circleci.sshRepositoryURL or circleci.httpsRepositoryURL properties of your .nsremote.config.json.

For example:

{{your-app-root}}/.nsremote.config.json

{
    "circleci": {
        "httpsRepositoryURL": "{{an HTTPS GitHub repository url}}"
    }
}

NOTE: When using the HTTPS URL, you should also set the GITHUB_ACCESS_TOKEN Local Environment Variable.

or

{{your-app-root}}/.nsremote.config.json

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

NOTE: When using the SSH URL, you should have an SSH key with a write access configured on your local machine.

WARNING: This sync repository be used to sync your local code changes with the Circle CI virtual machines. If the specified repository is public, make sure that your app does NOT have any sensitive data (e.g. secrets) which are not git ignored.

Once you setup the sync repository, you just need to set the CIRCLE_CI_API_ACCESS_TOKEN environment variable on your local machine. Take a look at the Set Local Environment Variable section for more details.

Android Builds Setup

No additional configurations needed. Just follow the basic setup.

iOS Builds Setup

In order to get started with the Fastlane based Circle CI iOS build, you will need an onetime access to a macOS machine and an administration access to a paid apple developer account.

  1. Follow the basic setup.
  2. Get a macOS machine (you will need it only during this setup).
  3. Download Fastlane.
  4. Setup the iOS signing in a private GitHub repository using the fastlane match development command and following the Git Repository flow. You could also run the fastlane match appstore if you plan to use the remote builds for production. You could read more about fastlane match features and its the iOS code signing management in the following article: https://docs.fastlane.tools/actions/match/.

IMPORTANT: Remember the appleId, signingRepositoryUrl and the match password that you provide to the fastlane match commands as you will need them in the next step.

  1. Set the IOS_SIGNING_REPO_URL, IOS_APPLE_ID and MATCH_PASSWORD remote environment variables. Take a look at the Set Remote Environment Variable section for more details.

  2. Add a private SSH key without password for accessing the {{IOS_SIGNING_REPO_URL}} in the SSH Permissions settings page of your sshRepositoryURL CircleCI project as shown in the image below:

Circle CI ssh keys page

Android Publish Setup

In order to get the Android Publishing working in the Fastlane based Circle CI builds, you will need to be the owner of a paid Google Play Account and follow the step below:

  1. Follow the basic setup.
  2. Follow the Fastlane upload_to_play_store setup.
  3. Base64 encode the generated json file and set it to the PLAYSTORE_ACCOUNT_BASE_64_JSON remote environment variable. Take a look at the Set Remote Environment Variable section for more details.

iOS Publish Setup

In order to setup the iOS publish in the Fastlane based Circle CI flow, you will need an administration access to a paid apple developer account and follow the steps below:

  1. Visit appleid.apple.com/account/manage.
  2. Login with the user specified in the IOS_APPLE_ID remote environment variable.
  3. Generate a new application specific password.
  4. Set the password to the FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD remote environment variable. Take a look at the Set Remote Environment Variable section for more details.
  5. Visit appstoreconnect.apple.com
  6. Copy the apple_id (should be something like 2457129416) of the app you want to publish and set it to the IOS_APPSTORE_CONNECT_APP_ID remote environment variable. Take a look at the Set Remote Environment Variable section for more details.

Set Local Environment Variable

The local environment variable can be set just like a regular environment variables on your local machine. However, if you don't wanna set environment variable on your local machine or you want to easily share the variables between multiple machines, the local environment variables could be also set in the local property of the git ignored .nsremote.env.json file. For example:

{
  "local": {
    "CIRCLE_CI_API_ACCESS_TOKEN": "{{the value of your Personal API Token mention in the prerequisites section above}}",
    "GITHUB_ACCESS_TOKEN": "{{the GitHub access token for accessing the HTTPS sync repo URL, skipped when using the sshRepositoryURL}}"
  },
  "remote": {}
}

Set Remote Environment Variable

If you use the sync repository for just a single app, you could directly set the environment variables in its Circle CI project as shown in the image blow:

Circle CI env vars page

If you don't wanna set environment variable in the sync repository Circle CI project (e.g. if you want to reuse the same sync repository for multiple apps with different iOS code signing), the remote environment variables could be set/overridden at app level using the remote property of the git ignored .nsremote.env.json file. For example:

{
  "local": {},
  "remote": {
    "IOS_APPLE_ID": "{{the apple id used by the Fastlane commands}}",
    "IOS_SIGNING_REPO_URL": "{{the private github repository used in the fastlane match commands above}}",
    "MATCH_PASSWORD": "{{the match password set in the match commands above}}",
    "PLAYSTORE_ACCOUNT_BASE_64_JSON": "{{the base64 encoded JSON file generated from your play store account}}"
  }
}

Security

The sensitive data is stored in environment variables in the Circle CI project (uploaded using https calls) and used directly from the variables. The iOS signing is managed by the fastlane match tool and stored encrypted in a private GitHub repository. The android keystore provided by --key-store-path is preprocessed by the plugin, base64 encoded and uploaded to the above-mentioned Circle CI environment variables.