Automatic Build for Ionic Android APK and Bundle using Github Actions

Posted by Harald Nezbeda on Sun 01 March 2020

Automating the build process will increase the efficiency of the development team. It will stop the frustration caused by setting up the build environment on the machine of each developer, it helps find build issues much faster and it also helps documenting the build process is a workflow file (in case it is required to be run elsewhere).

The more we reduce ourselves to machines in the lower things, the more force we shall set free to use in the higher. Anna Brackett

In this tutorial I will show how a build pipeline for an Ionic App can be created using Github Actions but the practices can be used with any other CI system such as Travis, Gitlab CI, Circle CI or Bitbucket Pipelines.

Prerequisites

In order to follow this tutorial you should have a github account and a repository with an Ionic project. You should also have some basic understanding of how pipelines work and Github Actions.

A full implementation is available in the ND Calculator repository.

Setup

A workflow file is required, for example .github/workflows/build.yml. The workflow should be triggered on push and on any new pull_request. The entire workflow will be based on an Ubuntu image.

name: Build Android

on: [push, pull_request]

jobs:
  build:
    name: Build APK
    runs-on: ubuntu-latest
    steps:

Build Steps

There are several steps we need to take care in order to perform the entire workflow and they can be grouped as follows:

  • Environment Setup
  • Dependency Installation
  • Application Build Tasks
  • Artifact generation

Environment Setup

We can make use of existing workflows that help us setup the environment. An Ionic app requires Java (for the Android build) and Node (for managing the frontend dependencies):

steps:
  - name: Checkout source
    uses: actions/checkout@v2

  - name: Setup java
    uses: actions/setup-java@v1
    with:
        java-version: 1.8

  - name: Setup Node.js
    uses: actions/setup-node@v1
    with:
        node-version: 13.x

Dependency Installation

The workflow needs to take care of installing Cordova, Ionic, the application dependencies and the Android SDK. Ionic and Cordova need to be installed globally as they will be used in future commands. The application dependencies are installed relative to the application directory and the Android SDK will be installed using the Ionic CLI that was installed previously by using ionic cordova platform.

steps:
  - name: Install Cordova
    run: npm install -g cordova

  - name: Install Ionic
    run: npm install -g @ionic/cli

  - name: Install app dependencies
    run: npm install

  - name: Add Android platform
    run: ionic cordova platform add android@latest

Application Build Tasks

At this step in the workflow a dev build and a release build are done. Both of them will generate APK files located in platforms/android/app/build/outputs/apk/. The development build can be installed directly on a Phone where the installation via APK is enabled. The release build needs to be signed before it can be installed as documented here.

After the release build the gradlew file is available under ./platforms/android/. This executable allows you to create an Android App Bundle. A dev and a release bundle will be available in platforms/android/app/build/outputs/bundle/ after running the ./gradlew bundle command.

steps:
  - name: Build Android Dev APK
    run: ionic cordova build android

  - name: Build Android Release APK
    run: ionic cordova build android --release --prod

  - name: Generate the Android App Bundle
    working-directory: ./platforms/android/
    run: ./gradlew bundle

Artifact generation

The scope of the entire workflow is to outsource the build process. At this point we will declare what should be stored from the build as by default all is thrown away after execution ends.

The following files are avaialble after the previous builds (all paths are relative to platforms/android/app/build/outputs/):

  • Dev APK: apk/debug/app-debug.apk
  • Release APK (unsigned): apk/release/app-release-unsigned.apk
  • Dev bundle: bundle/dev/app.aab
  • Release bundle(unsigned): bundle/release/app.aab
steps:
  - name: Upload dev APK
    uses: actions/upload-artifact@v1
    with:
      name: app-dev
      path: platforms/android/app/build/outputs/apk/debug/app-debug.apk

  - name: Upload release bundle
    uses: actions/upload-artifact@v1
    with:
      name: app-release
      path: platforms/android/app/build/outputs/bundle/release/app.aab

In order to publish the aab file on Google Play you need to use app signing. Alternatively you can use the release APK file located platforms/android/app/build/outputs/apk/release/app-release-unsigned.apk and signed it manually but be aware that this is build is slightly larger.

Final Workflow

Bellow is the implementation you may end up with:

name: Build Android

on: [push, pull_request]

jobs:
  build:
    name: Build APK
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v2

      - name: Setup java
        uses: actions/setup-java@v1
        with:
          java-version: 1.8

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 13.x

      - name: Install Cordova
        run: npm install -g cordova

      - name: Install Ionic
        run: npm install -g @ionic/cli

      - name: Install app dependencies
        run: npm install

      - name: Add Android platform
        run: ionic cordova platform add android@latest

      - name: Build Android Dev APK
        run: ionic cordova build android

      - name: Build Android Release APK
        run: ionic cordova build android --release --prod

      - name: Generate the Android App Bundle
        working-directory: ./platforms/android/
        run: ./gradlew bundle

      - name: Upload dev APK
        uses: actions/upload-artifact@v1
        with:
          name: app-dev
          path: platforms/android/app/build/outputs/apk/debug/app-debug.apk

      - name: Upload release bundle
        uses: actions/upload-artifact@v1
        with:
          name: app-release
          path: platforms/android/app/build/outputs/bundle/release/app.aab

Workflow Result

Github Action results for Ionic build

This image shows the result of a successful completed workflow:

  1. Indicated each step define din the workflow
  2. Lists the artifacts with the dev and release build
  3. Lists the time required for each task to complete.

The workflow takes from 5 to 7 minutes to complete. It will be triggered on each new push or pull request as seen in the list bellow (most actions where triggered by pull requests added by dependabot)

Github Action results list for Ionic build