Deploy Xamarin.Forms Apps to App Center from a Azure Multi-Stage Pipeline using Templates and Environments that Require Manual Approval

Wow, that title’s a mouthful, and I didn’t add in there that I’ve just pushed v0.2.0 release of the Pipeline Templates repository. In this post we’re going to add stages to a YAML based Azure DevOps pipeline in order to deploy a Xamarin.Forms application to AppCenter for testing. We’ll also be using on the of the latest features of the Azure DevOps YAML based pipelines, Environments, to insert a manual approval gate into our multi-stage pipeline.

Pipeline Templates v0.2.0

Before we get into talking about releasing apps to AppCenter I just wanted to reiterate that there is a new release of the Pipeline Templates repository with the following changes:

  • Added a new parameter, stage_name, to iOS, Android and Windows build templates. It has a default value, which matches the value previously specified on the stage element in the template, so won’t break any existing builds. This parameter can be set by the calling pipeline so that the stage is given a known name, which can then be referenced by other stages in the dependsOn element.
  • Added deployappcenter.yml template that can be used to deploy iOS, Android and Windows apps to AppCenter. For Android, if the application_package parameter is an .aab file, the calling pipeline will also need to supply keystore information. AppCenter doesn’t support .aab files, so the pipeline uses bundletool to generate and sign a fat apk, which is submitted to AppCenter.

Deploy to AppCenter

With a classic pipelines in Azure DevOps, you can setup separate build and release pipelines. However, YAML pipelines don’t differentiate between build and release pipelines; instead you can split a single pipeline into multiple stages (as we demonstrated in the previous post when we used different templates to create different stages in the build process).

To deploy apps to AppCenter we could simply create a template, similar to what we did with the build templates, that includes the tasks necessary to deploy to AppCenter, and then add new stages to our pipeline for each app we want to deploy. However, this would limit our ability to take advantage of some of the deployment specific features that are available in Azure DevOps. For this reason, the AppCenter template makes use of a deployment job in order to do the steps necessary to release an app to AppCenter.

Using the AppCenter Template

The following YAML pipeline provides an example of using the new AppCenter deployment template to deploy Windows (UWP), Android and iOS applications to AppCenter. Note that the ref element for the repository resource has been updated to point to the v0.2.0 tag.

resources:
  repositories:
    - repository: builttoroam_templates
      type: github
      name: builttoroam/pipeline_templates
      ref: refs/tags/v0.2.0
      endpoint: github_connection
  
variables:
  - group: 'Inspector XF Build Variables'
  
stages:
## Build stages excluded for brevity
- template:  azure/mobile/[email protected]_templates
  parameters:
    stage_name: 'Deploy_Windows'
    depends_on: 'Build_Windows'
    environment_name: 'Inspector-Alpha'
    artifact_name: 'inspector-build'
    artifact_folder: 'Windows_output'
    application_package: 'Inspector-XF-Windows.appxbundle'
    appcenter_service_connection: 'AppCenterInspectorCI'
    appcenter_organisation: 'thenickrandolph'
    appcenter_applicationid: 'Inspector-XF-UWP'
    appcenter_release_notes: 'Release from deploy pipeline'

- template:  azure/mobile/[email protected]_templates
  parameters:
    stage_name: 'Deploy_Android'
    depends_on: 'Build_Android'
    environment_name: 'Inspector-Alpha'
    artifact_name: 'inspector-build'
    artifact_folder: 'Android_output'
    application_package: 'Inspector-XF-Android.aab'
    appcenter_service_connection: 'AppCenterInspectorCI'
    appcenter_organisation: 'thenickrandolph'
    appcenter_applicationid: 'Inspector-XF-Android-Alpha'
    appcenter_release_notes: 'Release from deploy pipeline'
    secure_file_keystore_filename: '$(android_keystore_filename)'
    keystore_alias: '$(android_keystore_alias)'
    keystore_password: '$(android_keystore_password)'

- template:  azure/mobile/[email protected]_templates
  parameters:
    stage_name: 'Deploy_iOS'
    depends_on: 'Build_iOS'
    environment_name: 'Inspector-Alpha'
    artifact_name: 'inspector-build'
    artifact_folder: 'iOS_output'
    application_package: 'Inspector-XF-iOS.ipa'
    appcenter_service_connection: 'AppCenterInspectorCI'
    appcenter_organisation: 'thenickrandolph'
    appcenter_applicationid: 'Inspector-XF-iOS-Alpha'
    appcenter_release_notes: 'Release from deploy pipeline'

There are a couple of prerequisites that need to be setup in order for the deploy stages to work:

  • Each deploy stage specifies a depends_on property. This needs to correlate to the stage_name property specified on the corresponding build stage.
  • The artifact name, artifact folder and application_package properties need to match to the values used in the corresponding build stage.
  • A Service Connection needs to be established between Azure DevOps and AppCenter (in this case it was given the name ‘AppCenterInspectorCI’)
  • An application needs to be registered in AppCenter for each target platform. Each deploy stage needs the organisation (ie username or org_name) and applicationid (app_identifier). See the documentation on the AppCenterDistribute task for more information on how to find these values for your AppCenter apps.

Manual Approval with Environments

I mentioned earlier that using a deployment job would allow us to take advantage of deployment specific features. This is an area that’s currently under development and we’d expect to see more features lighting up in this area over time.

One feature that’s available today is the ability to add manual approval requirement to a deployment job. However, unlike in the classic pipeline where you’d create a manual approval requirement directly on the release pipeline, on a YAML pipeline you actually need to associated the deployment job with an environment and then add a manual approval on the environment.

You may have noticed that each of the deploy stages in the example YAML specified the environment_name property. This defines which environment you’re going to be deploying to. At this stage the only thing you can use this for in terms of deploying a mobile application is to require manual approval for the stage to continue. Let’s step through creating the environment and the approval requirement and you’ll see what I mean.

Create an Azure Pipelines Environment

Under the Pipelines tab, select Environments and then click the Create environment button in the center of the screen.

Next, provide a name for your environment and click Create. At this stage we don’t need to define any resources, so you can leave the default selection of “None”. The name that you specify for your environment has to match what you use as the environment_name property on the template.

Adding Manual Approval to the Environment

In order to add a manual approval requirement to an environment, simply open the environment (if you’ve just created the environment you’re already there). From the drop-down menu in the top-right corner, select Approvals and checks.

Next, click the + button in the top right corner.

Select Approvals, and then click Next

In the Approvals flyout you can specify a list of users and/or groups that need to approve a release to the environment. If you specify multiple users, each user needs to approve the release. If you specify a group, only one person in the group needs to approve the release.

In the Approvals flyout you can also specify a timeout; if the deployment isn’t approved for an environment within the timeout, the pipeline will fail.

Note: Currently there are no emails, or other notifications, sent to approvers. If you limit the timeout, once the specified period has elapsed if the environment hasn’t been approved, the pipeline fail and a notification will be sent out. The stage in the pipeline that failed can then be manually run and again, approval for the environment will be required.

Running the Build and Deploy Pipeline

Now when we run the pipeline, what we see in the portal is three different rows (one for each platform) with two stages (a build and deploy stage).

We’ve set the dependsOn element on each of the build stages to an empty array (ie []) meaning that they have no dependencies (btw the default is that stages will be done in the sequence that they appear in the YAML file, unless you indicate there should be no dependencies). Depending on how many build agents you have at your disposal the build stages may run in sequence, or in parallel.

Eventually, when each of the build stages completes, the corresponding deploy stage will light up indicating that it’s waiting for a check to be passed. There’s also a message box inserted into the interface to draw attention to the required approval.

Once all three of the build stages are complete, there are 3 approvals required; one for each of the deploy stages. The way we’ve structured the pipeline you have to approve the deployment for each platform.

If you wanted to require only a single approval for all three platforms you could inject an additional stage that was dependent on all three build stages. The approval would be required for this single stage, and then each of the subsequent deploy stages would be permitted to continue without further checks. The downside of this would be that you would have to wait for all builds to fail before you could deploy the app to any platform.

Summary

In this post we’ve looked at using a pipeline template for deploying Xamarin.Forms applications to AppCenter for testing across Windows (UWP), iOS and Android. In actual fact, and what I didn’t point out earlier, the deploy template can be used for any iOS, Android or Windows (UWP) app, not just a Xamarin.Forms application.

I also walked through setting up an environment so that you could add a manual approval step to the deployment process. Whilst the YAML pipelines don’t yet have all the features of the classic release pipeline, you can see from the way that the components connect and the UI that’s built in the portal that the foundations have been laid for future features to be built on.

Repacking and Resigning an Android APK to Target Different Environments

In my previous post talking about targeting different environments I ended with the proposition that what we need to be able to do as part of the release pipeline for an app is to adjust the configuration file that’s included in the app package. In this post I’m going to manually walk through what this process would look like for an Android APK (and yes, before you all jump up and down and say that I should be using an app bundle, I’m aware of this but let’s do this process step by step).

Ok to begin, what I need is a release-ready APK and for the purpose of this post I’m going to use a Flutter app. The process I’m going to describe will work for any Android APK regardless of the toolchain/framework/technology set that you’re using to build your app. The only difference with say a Xamarin.Forms application would be how you package the configuration file; the code you’d need to write to read the configuration file and of course the XAML for displaying the contents to the screen.

Basic App Structure

My sample Flutter app starts with the default app template you get when creating a new Flutter app in VS Code. I then added a single text file, config.txt, to the assets folder; included the file in the pubspec.yaml and then adjusted the _MyHomePageState class to load the contents of the file (a basic walk through of reading files that are included in the app package are included in this post).

class _MyHomePageState extends State<MyHomePage> {
  String config = '';

  @override
  void initState() {
    super.initState();

    loadConfig(context);
  }

  void loadConfig(BuildContext context) async {
    config =
        await DefaultAssetBundle.of(context).loadString('assets/config.txt');
    setState(() {});
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'App configuration:',
            ),
            Text(
              '$config',
              style: Theme.of(context).textTheme.display1,
            ),
          ],
        ),
      ),
    );
  }
}

The contents of the config.txt file simply says “***Default App Config***” and running the app looks like:

Release Ready APK

In order to walk through the process of repackaging an APK, I firstly need to make sure I have a release-ready APK. By this I mean that I have an APK that’s been built in release mode and that has been signed, as if I were going to submit it to the Google Play store.

The Flutter documentation has very clear instructions on how to package and sign your application. I followed these instructions to generate a keystore that is used as part of the Flutter build process to sign the application.

In order to test to make sure your APK is good to go, simply copy it to a real device and test that you can install and run it. For this I simply uploaded the APK to dropbox and then opened the file on my device. You could also attach to an email or even side load directly via USB cable if you choose.

Repackaging to Change App Configuration

The basic process we want to follow is:

  • Unpack the APK
  • Modify the config.txt file
  • Repack the APK
  • Sign the APK

Unpacking the APK

In order for us to be able to modify the config.txt file that’s packaged in the app, we first need to unpack the APK. For this I’m going to use the APKTool utility. Follow the installation instructions to make sure you have the latest version and the appropriate directories added to the PATH variable (you may need to add the Java directory to your PATH).

Once installed, to unpack an APK you can simply call the APKTool with the decode, or just “d”, argument:

   apktool d app-release.apk -o extracted_apk

Note that I specified the “-o” argument to allow me to specify the output folder.

Modify the Config.txt

In this example we’re simply going to modify the config.txt file that we have included in the app package. You could be more fancy and include a json or xml configuration file but essentially all you’re going to do in this step is modify the contents, or replace the file entirely.

In the case of my sample Flutter app, the location of the config.txt is in the sub-folder “\assets\flutter_assets\assets”. If you’re application is built using Xamarin.Forms, your configuration file may be located in a different folder – you just need to search the extracted folder and locate the file.

I’ve changed the contents of the file to “***Modifited App Config***”

Repack the APK

After making the change to the config.txt file we then need to repack the APK. For this we can again use the APKTool, this time specifying the build, or “d”, argument:

apktool b extracted_apk -o app-release-mod.apk

More detailed information on the APKTool is available from their documentation page.

Sign the APK

The last step is to sign the APK and for this I’m going to use the Uber Apk Signer along with the keystore I setup as part of configuring the Flutter release build.

java -jar uber-apk-signer-1.1.0.jar -a app-release-mod.apk --ks c:\<<path to keystore>>\key.jks --ksAlias key --ksKeyPass <<password>> --ksPass <<password>> -o app-release-mod-signed

And that’s it – if we check in the app-release-mod-signed folder there’ll be a new APK that’s signed and ready to go.

Copy the application to your device and run it and you’ll see the updated configuration value (and yes, complete with spelling mistake!!)

Repackaging Apps During Release Process

As you can see from this process, it’s not too hard to adjust a configuration value by repacking an Android APK. You can simply include the APKTool and the Uber-Apk-Signer alongside your application and script out these steps as part of your Release pipeline.