Getting started with Ionic/Cordova apps

You can use Cordova and Ionic frameworks to develop cross-platform apps. Bitrise can help you with its automated testing, code signing and deployment procedures so that you can ship your iOS and/or Android app/s to the respective marketplace in no time! If your Workspace has more than one concurrency, you can have Android and iOS builds run simultaneously. Now let us guide you through the process!

Do you have a Bitrise account?

Make sure you have signed up to bitrise.io and can access your Bitrise account. There are multiple ways of registering an account:

Adding an Ionic/Cordova app to Bitrise

Wait while Bitrise is validating your project. We look for your configuration files and set up your app based on them.

  1. Go to your Bitrise Dashboard.

  2. Click the + sign on the top menu bar and select , which takes you to the Create New App page.

  3. Choose the account you wish to add the app to.

  4. Set the privacy of the app to either Private or Public and click Next.

  5. Select the Git hosting service that hosts your repository, then find and select your own repository that hosts the project.

  6. When prompted to set up repository access, click No, auto-add SSH key.

  7. Type the name of the branch that includes your project’s configuration - main, for example, - then click Next.

  8. At Project Build configuration, you can select which platform to build your app for. You can select:

    • iOS.

    • Android.

    • iOS and Android (where the Android build gets built first).

    Getting started with Ionic/Cordova apps
    Getting started with Ionic/Cordova apps
  9. Register a webhook when prompted so that Bitrise can start a build automatically when code is pushed to your repository.

    This also kicks off your first build on the primary Workflow - click the message and it will take you to the build page. The first build does not generate an .apk and an .ipa yet, however, you can already check out the project’s logs on the build’s page.

Installing dependencies for Ionic/Cordova apps

If the Bitrise project scanner has successfully scanned your Ionic/Cordova project, Run npm command or Run yarn command Steps will be included in your default Workflows. These Steps can install the missing Javascript dependencies for your app.

For native Android dependencies, you can use the Install missing Android SDK components Step.

For native iOS dependencies, you can use, among others, the Brew install Step or the Run CocoaPods install Step.

To install Javascript dependencies with npm:

Using Yarn instead of npm

In this guide, we're using npm to install Javascript dependencies. However, you can use the Run yarn command Step: it can install missing JS dependencies without any additional configuration required.

  1. Open your app on Bitrise.

  2. Go to the Workflow tab.

  3. Select a Workflow from the WORKFLOW dropdown menu.

    Installing any additional tools
  4. Make sure your Workflow includes the Run npm command Step.

  5. In the npm command with arguments to run input field, type install.

    Getting started with React Native apps

Testing Ionic/Cordova apps

You can run unit tests for Ionic/Cordova apps on Bitrise by using our Karma Jasmine Test Runner or Jasmine Test Runner Steps.

If your Cordova/Ionic project has a Karma Jasmine dependency in its package.json file, our scanner will detect it when you're adding your app and automatically insert the respective testing Step into your Workflow. If this dependency is missing from your project, you can manually insert one of our testing steps to your Workflow using our Workflow Editor.

  1. Open your app on Bitrise.

  2. Go to the Workflow tab.

  3. Make sure you have a testing Step in your Workflow.

    Important

    During the build process, your dependencies must be installed before you could run tests.

    You can choose between the Karma Jasmine Test Runner and the Jasmine Test Runner Steps.

Example 1. Cordova app configuration with Karma Jasmine Test Runner

In this example, you can find a bitrise.yml configuration that includes a Workflow called primary. This Workflow includes the Karma Jasmine Test Runner Step.

primary:
    steps:
    - activate-ssh-key@4.0.3:
        run_if: '{{getenv "SSH_RSA_PRIVATE_KEY" | ne ""}}'
    - git-clone@4.0.11: {}
    - script@1.1.5:
        title: Do anything with Script step
    - npm@0.9.1:
        inputs:
        - command: install
    - karma-jasmine-runner@0.9.1: {}
    - deploy-to-bitrise-io@1.3.15: {}

Code signing Ionic/Cordova apps

If you want to build an app for iOS or Android, you need to upload the platform-specific files into the Code Signing tab of the Workflow Editor. You can also generate builds for both platforms which requires uploading all code signing files of the platforms.

Signing your iOS project

Code signing your iOS project depends on what you wish to do with the exported IPA file. You can sign your file so that you can test it on registered devices or you can use different code signing settings to build an app that is ready for distribution. You can also do both in the same Workflow!

iOS code signing

This guide is only an introduction to iOS code signing. For more details, check out our dedicated guides: iOS code signing

  1. Generate the native Xcode project locally from your Ionic or Cordova project by calling cordova platform add ios or ionic cordova platform add ios.

  2. Collect your code signing files with our codesigndoc tool.

    You can use the tool to immediately upload the collected files to Bitrise. Otherwise, upload them manually to the Code signing tab in the Workflow Editor.

    Note

    The type of code signing files required depends on your requirements. We strongly recommend uploading at least:

    • A Developer and an App Store type code signing certificate.

    • A Development and a Distribution type provisioning profile.

  3. Open your app on Bitrise.

  4. Go to the Workflow tab.

  5. Select a Workflow from the WORKFLOW dropdown menu.

    Installing any additional tools
  6. Make sure that you have the Certificate and profile installer Step in your workflow.

  7. Add the Generate cordova build configuration Step to your Workflow.

    This Step does all the configuration needed for the next step, which is Cordova archive or Ionic archive.) It must come after the Certificate and profile installer Step.

  8. Fill in the required input for the Step.

    Please note that both the Code Signing Identity and the Provisioning Profile are required inputs for iOS apps even though they are not marked as such.

    • Build configuration: you can set it to either debug or release.

    • Code Sign Identity: enter a Developer or a Distribution identity.

    • Provisioning Profile: enter the appropriate Provisioning Profile.

    • Packaging Type: this controls what type of build is generated by Xcode. Set the type of code signing you need.

That's it. When you run a build, it will generate a signed IPA for you.

Signing your Android project

All Android apps must be digitally signed with a certificate before they can be installed on Android devices. On Bitrise, you can use our dedicated Step for this purpose but first you'll need a keystore file.

  1. .

  2. Open your app on Bitrise.

  3. Go to the Workflow tab.

  4. Go to the Code Signing tab.

  5. Drag-and-drop your keystore file to the ANDROID KEYSTORE FILE field.

  6. Fill out the Keystore password, Keystore alias, and Private key password fields and click Save metadata.

    Getting started with Android apps
  7. Select a Workflow from the WORKFLOW dropdown menu.

  8. Add the Generate cordova build configuration Step to your Workflow.

    If you uploaded your keystore file and filled out the metadata, the required inputs of the Step are already filled and require no more configuration from you.

Deploying Ionic/Cordova apps

To build and deploy an Ionic or Cordova app on Bitrise, you need to digitally sign both the Android and iOS project (if you're building both) and then use the Cordova Archive or the Ionic Archive Step to build the app before deploying it.

You can deploy the successfully built app to:

  • Online stores, such as the Google Play Store or Apple's App Store.

  • Bitrise.io: the generated binaries will be available on the APPS & ARTIFACTS tab of the build's page. You can download them from there or share them with others via the public install page.

Deploying a cross-platform app to bitrise.io

The Deploy to bitrise.io Step uploads all the artifacts related to your build into the APPS & ARTIFACTS tab on your Build’s page.

You can share the generated app file (AAB for Android or an IPA file for iOS) with your team members using the public install page. The public install page is a URL you can share with others who can install the generated app binary on their device. You can also notify user groups or individual users that your AAB/APK or IPA file has been built.

  1. Open your app on Bitrise.

  2. Go to the Workflow tab.

  3. Select a Workflow from the WORKFLOW dropdown menu.

    Installing any additional tools
  4. Make sure you have the Deploy to bitrise.io Step in your Workflow.

  5. In the Notify: User Roles, add the role so that only those get notified who have been granted with this role. Or fill out the Notify: Emails field with email addresses of the users you want to notify.

    Make sure you set those email addresses as Secrets! These details can be also modified under Notifications if you click the eye icon next to your generated binary in the APPS & ARTIFACTS tab.

  6. If you want the Step to generate a public install page for you, set the Enable public page for the App? input to true.

Deploying your Android project to Google Play

You can use the Deploy to Google Play Step in your Workflow to upload your digitally signed AAB/APK to the Google Play Store.

  1. Add the Cordova archive or the Ionic archive Step to your Workflow.

    Note that if you’re building for both iOS and Android in one project, and either of your apps fails, the whole Cordova archive/Ionic archive Step will fail.

  2. Fill in the required inputs.

    • The Platform input needs to be set to device.

    • The Build command configuration input must match the Build configuration input of the Generate cordova build configuration Step.

    The archive Step must come after the Generate cordova build configuration Step in the Workflow.

  3. Configure code signing for your app.

  4. Configure Google Play access.

    You only need to do this for your very first Google Play deployment of the app.

  5. Make sure you have the Deploy to Google Play Step after the Cordova Archive or Ionic Archive Step in your Workflow.

  6. Fill out the required input fields as follows:

    • Service Account JSON key file path: This field can accept a remote URL so you have to provide the Env Var which contains your uploaded service account JSON key. For example: $BITRISEIO_SERVICE_ACCOUNT_JSON_KEY_URL.

    • Package name: The package name of your Android app.

    • Track: The track where you want to deploy your APK (for example, alpha/beta/rollout/production or any custom track you set).

Deploying your iOS project to the App Store

  1. Add the Cordova archive or the Ionic archive Step to your Workflow.

    Note that if you’re building for both iOS and Android in one project, and either of your apps fails, the whole Cordova archive/Ionic archive Step will fail.

  2. Fill in the required inputs.

    • The Platform input needs to be set to device.

    • The Build command configuration input must match the Build configuration input of the Generate cordova build configuration Step.

    The archive Step must come after the Generate cordova build configuration Step in the Workflow.

  3. Configure iOS code signing for your iOS project.

  4. Add the Deploy to iTunes Connect - Application Loader Step to your Workflow, after the Xcode Archive & Export for iOS Step but preferably before the Deploy to Bitrise.io Step.

  5. Provide your Apple credentials in the Deploy to iTunes Connect - Application Loader Step.

    The Step will need your:

    • Apple ID.

    • Password or, if you use two-factor authentication on App Store Connect, your application password.

    Don’t worry, the password will not be visible in the logs or exposed.

  6. Start a build.