Sign a mobile app

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

To sign and provision a mobile app for Android or Apple operating systems, you need to manage signing certificates and Apple provisioning profiles. This article describes how to securely manage certificates and profiles for signing and provisioning your app in Azure Pipelines.

Note

You need at least one agent to run a build or release. You can use a Microsoft-hosted Linux, macOS, or Windows build agent, or set up your own agent. For more information, see Build and release agents.

Sign your Android app

Follow these steps to sign your Android app while keeping your signing certificate secure.

Upload the keystore file

  1. Obtain a keystore file that contains your signing certificate. The Android documentation describes the process of generating a keystore file and its corresponding key.

  2. In Azure Pipelines, go to Libraries > Secure files. Select + Secure file and upload your keystore file to the secure files library. During upload, your keystore is encrypted and securely stored.

Add the signing task to the pipeline

Add the AndroidSigning@3 task to your YAML pipeline after the step that builds your app. In the AndroidSigning@3 task:

  • <apkFiles> is required and is the path and names of the APK files to be signed. The default is **/*.apk.
  • <apksign> must be true, which is the default.
  • <keystore-file> is the name of your uploaded keystore file in the secure files library.
  • <apksignerKeystorePassword> is the password to the unencrypted keystore file.
  • <apksignerKeystoreAlias> is the key alias for the signing certificate.
  • <apksignerKeyPassword> is the password for the key associated with the specified alias.

You can set and use variables in the YAML, or you can set the variables using the Variables tab in the Azure Pipelines UI and refer to them in the YAML.

variables:
  keystore-password: <keystore file password>
  key-alias: <key alias for the signing certificater>
  key-password: <password for the key associated with the alias>

steps:
- task: AndroidSigning@3
  displayName: 'Signing and aligning APK file(s) **/*.apk'
  inputs:
    apkFiles: '**/*.apk'
    apksign: true
    apksignerKeystoreFile: <keystore-filename.keystore>
    apksignerKeystorePassword: $(keystore-password)
    apksignerKeystoreAlias: $(key-alias)
    apksignerKeyPassword: $(key-password)

Any build agent can now securely sign your app without any certificate management on the build machine itself.

Sign your Apple iOS, macOS, tvOS, or watchOS app

To sign and provision your app, your Xcode or Xamarin.iOS build needs access to your P12 signing certificate and one or more provisioning profiles. The following steps explain how to obtain these files.

Get your P12 signing certificate

  1. Export your development or distribution signing certificate to a .p12 file by using either Xcode or the Keychain Access app on macOS.

    • To export using Xcode:

      1. Go to Xcode > Preferences > Accounts.

      2. In the left column, select your Apple ID.

      3. On the right side, select your personal or team account and select Manage Certificates.

      4. Ctrl+Select the certificate you want to export and select Export certificate from the menu.

        Screenshot of exporting a certificate using Xcode.

      5. In the dialog box, enter the certificate name, location to save the file, and a password to secure the certificate.

    • Or, use the procedure described in iOS Signing to follow a similar process using the Keychain Access app on macOS or generate a signing certificate on Windows.

  2. Upload your P12 file to the Azure Pipelines secure files library. During upload, your certificate is encrypted and securely stored.

  3. In your pipeline, go to the Variables tab and add a variable named P12password with your certificate password as the value. Be sure to select the lock icon to secure your password and obscure it in logs.

Get your provisioning profile

If your app doesn't use automatic signing, you can download your app provisioning profile from the Apple Developer portal. For more information, see Edit, download, or delete provisioning profiles.

You can also use Xcode to access provisioning profiles that are installed on your Mac. In Xcode, go to Xcode > Preferences > Accounts. Select your Apple ID and your team and then select Download Manual Profiles.

In Azure Pipelines, upload your provisioning profile to the secure files library. During upload, your file is encrypted and securely stored.

Add the signing and provisioning tasks to the pipeline

To sign and provision your app, you can either install the certificate and profile during each build, or preinstall the files on a macOS build agent.

Install the certificate and profile during each build

Install the certificate and profile during each build when you don't have enduring access to the build agent, for example when you use hosted macOS agents. The P12 certificate and provisioning profile are installed at the beginning of the build and removed when the build completes.

  • Add the InstallAppleCertificate@2 task to your YAML pipeline before the Xcode or Xamarin.iOS task. In the code, replace <secure-file.p12> with the name of your uploaded .p12 file. Use the variable for the secure P12password.

    - task: InstallAppleCertificate@2
        inputs:
          certSecureFile: '<secure-file.p12>'
          certPwd: '$(P12password)'
    

    Note

    In the InstallAppleCertificate@2 task, the deleteCert parameter defaults to true, which removes the certificate after build.

  • Add the InstallAppleProvisioningProfile@1 task to your YAML before the Xcode or Xamarin.iOS task. Replace <secure-file.mobileprovision> with the name of your provisioning profile file.

    - task: InstallAppleProvisioningProfile@1
        inputs:
          provProfileSecureFile: '<secure-file.mobileprovision>'
    

    Note

    In the InstallAppleProvisioningProfile@1 task, the removeProfile parameter defaults to true, which removes the profile after build.

Any build agent can now securely sign your app without any certificate or profile management on the build machine itself.

Preinstall the certificate and profile on a macOS build agent

Instead of installing the signing certificate and provisioning profiles during the build, you can preinstall them on a macOS build agent. The files are then available for continued use by builds. Use this method only when you trust the people and processes that have access to the macOS keychain on the agent machine.

Preinstall the P12 certificate

  1. To install the P12 certificate in the default keychain, run the following command from a macOS Terminal window on the build agent. Replace <certificate.p12> with the path and name of your P12 file. Replace <password> with your P12 file's encryption password.

    sudo security import <certificate.p12> -P <password>
    
  2. Add a new variable to your pipeline named KEYCHAIN_PWD. Set the value as the password to the default keychain, which is normally the password for the user that starts the agent. Be sure to select the lock icon to secure this password.

Preinstall the provisioning profile

  1. Find the full name of your signing identity by opening a macOS Terminal window and entering security find-identity -v -p codesigning. You see a list of signing identities in the form iPhone Developer/Distribution: Developer Name (ID). If an identity is invalid, you see something like (CSSMERR_TP_CERT_REVOKED) after the identity.

  2. To install the provisioning profile on the agent machine, run the following command from a macOS Terminal window. Replace <profile> with the path to your provisioning profile file, and replace <UUID> with the provisioning profile UUID, which is the provisioning profile filename without the .mobileprovision extension.

    sudo cp <profile> ~/Library/MobileDevice/Provisioning Profiles/<UUID>.mobileprovision
    

Add signing and provisioning tasks that use the default keychain

  • Add the InstallAppleCertificate@2 task to your YAML pipeline before the Xcode or Xamarin.iOS task. In the code, set the following values:

    • certSecureFile: The name of your uploaded .p12 file.
    • certPwd: The variable for the secure P12password.
    • signingIdentity: The full name of your signing identity.
    • keychain: default, to allow access to the default keychain.
    • keychainPassword: The KEYCHAIN_PWD variable.
    • deleteCert: false, to retain the certificate between builds.
    - task: InstallAppleCertificate@2
      inputs:
        certSecureFile: '<secure-file.p12>'
        certPwd: '$(P12password)'
        signingIdentity: <full-signing-identity>
        keychain: default
        keychainPassword: `$(KEYCHAIN_PWD)
        deleteCert: false
    
  • Add the InstallAppleProvisioningProfile@1 task. In the code:

    • Set provProfileSecureFile to the name of your provisioning profile file.
    • Set removeProfile to false so the profile is retained between builds.
    - task: InstallAppleProvisioningProfile@1
        inputs:
          provProfileSecureFile: '<secure-file.mobileprovision>'
          removeProfile: false
    

The macOS build agent can now securely sign and provision your app for all builds without further certificate or profile management.

Reference the secure files in the Xcode or Xamarin.iOS build task

To use the secure certificate and profile in your pipelines, configure the following settings in your Xcode or Xamarin.iOS build tasks.

The secure files references in the build tasks use variables for the signingIdentity and the provisioningProfileUuid. These variables are automatically set by the Install Apple Certificate and Install Apple Provisioning Profile tasks for the certificate and provisioning profile you selected.

For Xcode:

- task: Xcode@5
  inputs:
    signingOption: 'manual'
    signingIdentity: '$(APPLE_CERTIFICATE_SIGNING_IDENTITY)'
    provisioningProfileUuid: '$(APPLE_PROV_PROFILE_UUID)'

For Xamarin.iOS:

- task: XamariniOS@2
    inputs:
      solutionFile: '**/*.iOS.csproj'
      signingIdentity: '$(APPLE_CERTIFICATE_SIGNING_IDENTITY)'
      signingProvisioningProfileID: '$(APPLE_PROV_PROFILE_UUID)'

The pipeline build agent now securely signs and provisions your app without further certificate or profile management on the build machine itself.

For more information about: