Build and deploy Xamarin apps with a pipeline

Azure DevOps Services

Get started with Xamarin and Azure Pipelines by using a pipeline to deploy a Xamarin app. You can deploy Android and iOS apps in the same or separate pipelines.

Prerequisites

Have the following items:

Get code

Fork the following repo at GitHub:

https://github.com/MicrosoftDocs/pipelines-xamarin

This sample is the FirstApp sample from the https://github.com/xamarin/xamarin-forms-samples repository. For more information on getting started with Xamarin, see Build your first Xamarin.Forms App.

Sign in to Azure Pipelines

Sign-in to Azure Pipelines. After you sign in, your browser goes to https://dev.azure.com/my-organization-name and displays your Azure DevOps dashboard.

Within your selected organization, create a project. If you don't have any projects in your organization, you see a Create a project to get started screen. Otherwise, select the New Project button in the upper-right corner of the dashboard.

Create the pipeline

  1. Sign in to your Azure DevOps organization and go to your project.

  2. Go to Pipelines, and then select New pipeline or Create pipeline if creating your first pipeline.

  3. Do the steps of the wizard by first selecting GitHub as the location of your source code.

  4. You might be redirected to GitHub to sign in. If so, enter your GitHub credentials.

  5. When you see the list of repositories, select your repository.

  6. You might be redirected to GitHub to install the Azure Pipelines app. If so, select Approve & install.

  1. On the Configure tab, select Xamarin.Android to build an Android project or Xamarin.iOS to build an iOS project. If you want to use the included sample .yml files, choose Existing Azure Pipelines YAML file and choose from one of the included sample pipelines (Android, iOS, or a combined pipeline that builds both).

  2. When your new pipeline appears, take a look at the YAML to see what it does. When you're ready, select Save and run.

    Save and run button in a new YAML pipeline

  3. If you created a new YAML file, commit a new azure-pipelines.yml file to your repository. After you're happy with the message, select Save and run again.

    If you want to watch your pipeline in action, select the build job. You now have a working YAML pipeline (azure-pipelines.yml) in your repository that's ready for you to customize!

  4. When you're ready to make changes to your pipeline, select it in the Pipelines page, and then Edit the azure-pipelines.yml file.

Read further to learn some of the more common ways to customize your pipeline.

Set up Xamarin tools

You can use Azure Pipelines to build your Xamarin apps without setting up your own infrastructure. Xamarin tools are preinstalled on Microsoft-hosted agents in Azure Pipelines. You can use macOS or Windows agents to run Xamarin.Android builds, and macOS agents to run Xamarin.iOS builds. If you're using a self-hosted agent, install either of the following tools:

For the exact versions of Xamarin that are preinstalled, refer to Microsoft-hosted agents.

Create a file named azure-pipelines.yml in the root of your repository. Then, add the following snippet to your azure-pipelines.yml file to select the appropriate agent pool:

# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/xamarin
pool:
  vmImage: 'macOS-12' # For Windows, use 'windows-2019'

Build a Xamarin.Android app

To build a Xamarin.Android app, add the following snippet to your azure-pipelines.yml file. Change values to match your project configuration. For more information about options, see the Xamarin.Android task.

variables:
  buildConfiguration: 'Release'
  outputDirectory: '$(build.binariesDirectory)/$(buildConfiguration)'

steps:
- task: NuGetToolInstaller@1

- task: NuGetCommand@2
  inputs:
    restoreSolution: '**/*.sln'

- task: XamarinAndroid@1
  inputs:
    projectFile: '**/*Droid*.csproj'
    outputDirectory: '$(outputDirectory)'
    configuration: '$(buildConfiguration)'
    msbuildVersionOption: '16.0'

Sign a Xamarin.Android app

For information about signing your app, see Sign your mobile Android app during CI.

Build a Xamarin.iOS app

To build a Xamarin.iOS app, add the following snippet to your azure-pipelines.yml file. Change values to match your project configuration. For more information about options, see the Xamarin.iOS task.

variables:
  buildConfiguration: 'Release'

steps:
- task: XamariniOS@2
  inputs:
    solutionFile: '**/*iOS.csproj'
    configuration: '$(buildConfiguration)'
    packageApp: false
    buildForSimulator: true

Sign and provision a Xamarin.iOS app - The PackageApp option

To generate a signed and provisioned Xamarin.iOS app .ipa package, set packageApp to true. Make sure you already installed the right Apple Provisioning Profile and Apple Certificates that match your App Bundle ID into the agent running the job.

To fulfill these mandatory requisites, use the Microsoft Provided tasks for installing an Apple Provisioning Profile and installing Apple Certificates.

- task: XamariniOS@2
    inputs:
      solutionFile: '**/*iOS.csproj'
      configuration: 'AppStore'
      packageApp: true

Tip

The Xamarin.iOS build task only generates an .ipa package if the agent running the job has the appropriate provisioning profile and Apple certificate installed. If you enable the packageApp option and the agent doesn't have the appropriate apple provisioning profile(.mobileprovision) and apple certificate(.p12) the build may succeed, but the .ipa isn't generated.

For Microsoft Hosted agents, the .ipa package is by default located under the following path:
{iOS.csproj root}/bin/{Configuration}/{iPhone/iPhoneSimulator}/

You can configure the output path by adding an argument to the Xamarin.iOS task:

- task: XamariniOS@2
    inputs:
      solutionFile: '**/*iOS.csproj'
      configuration: 'AppStore'
      packageApp: true
      args: /p:IpaPackageDir="/Users/vsts/agent/2.153.2/work/1/a"

This example locates the .ipa in the Build Artifact Staging Directory. It's ready to get pushed into Azure DevOps as an artifact to each build run. To push it into Azure DevOps, add a Publish Artifact task to the end of your pipeline.

For more information about signing and provisioning your iOS app, see Sign your mobile iOS app during CI.

Set the Xamarin SDK version on macOS

To set a specific Xamarin SDK version to use on the Microsoft-hosted macOS agent pool, add the following snippet before the XamariniOS task in your azure-pipelines.yml file. For details on properly formatting the version number (shown as 5_4_1 below), see How can I manually select versions of tools on the Hosted macOS agent?.

- script: sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1
  displayName: 'Select Xamarin SDK version'

Build Xamarin.Android and Xamarin.iOS apps with one pipeline

You can build and test your Xamarin.Android app, Xamarin.iOS app, and related apps in the same pipeline by defining multiple jobs in azure-pipelines.yml. These jobs can run in parallel to save time. The following complete example builds a Xamarin.Android app on Windows, and a Xamarin.iOS app on macOS, using two jobs.

# Xamarin.Android and Xamarin.iOS
# Build a Xamarin.Android and Xamarin.iOS app.
# Add steps that test, sign, and distribute the app, save build artifacts, and more:
# https://learn.microsoft.com/azure/devops/pipelines/ecosystems/xamarin

jobs:

- job: Android
  pool:
    vmImage: 'windows-2019'

  variables:
    buildConfiguration: 'Release'
    outputDirectory: '$(build.binariesDirectory)/$(buildConfiguration)'

  steps:
  - task: NuGetToolInstaller@1

  - task: NuGetCommand@2
    inputs:
      restoreSolution: '**/*.sln'

  - task: XamarinAndroid@1
    inputs:
      projectFile: '**/*droid*.csproj'
      outputDirectory: '$(outputDirectory)'
      configuration: '$(buildConfiguration)'
      msbuildVersionOption: '16.0'

  - task: AndroidSigning@3
    inputs:
      apksign: false
      zipalign: false
      apkFiles: '$(outputDirectory)/*.apk'

  - task: PublishBuildArtifacts@1
    inputs:
      pathtoPublish: '$(outputDirectory)'

- job: iOS
  pool:
    vmImage: 'macOS-12'

  steps:
  # To manually select a Xamarin SDK version on the Hosted macOS agent, enable this script with the SDK version you want to target
  # https://go.microsoft.com/fwlink/?linkid=871629
  - script: sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1 
    displayName: 'Select Xamarin SDK version'
    enabled: false

  - task: NuGetToolInstaller@1

  - task: NuGetCommand@2
    inputs:
      restoreSolution: '**/*.sln'

  - task: XamariniOS@2
    inputs:
      solutionFile: '**/*.sln'
      configuration: 'Release'
      buildForSimulator: true
      packageApp: false

Clean up resources

If you don't need the example code, delete your GitHub repository and Azure Pipelines project.

Next steps