Sign your mobile app

Azure Pipelines | TFS 2018 | TFS 2017.2

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, run and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

When developing an app for Android or Apple operating systems, you will eventually need to manage signing certificates, and in the case of Apple apps, provisioning profiles. This article describes how to securely manage them for signing and provisioning your app.

Tip: Use a Microsoft-hosted Linux, macOS, or Windows build agent, or set up your own agent. See Build and release agents.

This article covers:

Sign your Android app

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

  1. First, 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. Create your build pipeline from the Android or Xamarin.Android build template. Or, if you already have a build pipeline, add the Android Signing task after the task that builds your APK.

  3. Find the Android Signing task's Sign the APK checkbox and enable it.

  4. Next to the Keystore file field, click the settings icon and upload your keystore file to the Secure Files library. During upload, your keystore will be encrypted and securely stored.

  5. Once your keystore has been uploaded to the Secure Files library, select it in the Keystore file dropdown.

  6. Go to the Variables tab and add the following variables. In their Value column, enter your Keystore password, Key alias, and Key password.

    • keystore-password: Password to the unencrypted keystore file. Be sure to click the lock icon. This will secure your password and obscure it in logs.

    • key-alias: The key alias for the signing certificate you generated.

    • key-password: The password for the key associated with the specified alias. Again, be sure to click the lock icon.

      Android signing variables

  7. Go back to the Tasks tab and reference the names of your newly-created variables in the signing options.

    Android signing input values

Save your build pipeline, and you are all set! Any build agent will now be able to securely sign your app without any certificate management on the build machine itself.

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

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

Obtain your P12 signing certificate

After creating your development or distribution signing certificate, export it to a .p12 file using either Xcode or the Keychain Access app on macOS.

  1. To export using Xcode 8 or lower, go to Xcode > Preferences... > Accounts and select your Apple Developer account.

  2. Click View Details..., right-click on the signing identity you wish to export, and click Export....

  3. Enter a filename and password. Take note of the password as you will need it later.

    Xcode Export Cert

  4. Alternatively, follow a similar process using the Keychain Access app on macOS or generate a signing certificate on Windows. Use the procedure described in this article if you prefer this method.

Obtain your provisioning profile

You can download your app provisioning profile from the Apple Developer portal, unless your app uses automatic signing. You can also use Xcode to access those that are installed on your Mac.

  1. Using Xcode 8 or lower, go to Xcode > Preferences... > Accounts and select your Apple Developer account.

  2. Right-click the provisioning profile you want to use and select Show in Finder.

  3. Copy the highlighted file from Finder to another location and give it a descriptive filename.

    Xcode Show in Finder

Configure your build

There are two recommended ways for your build to access signing certificates and provisioning profiles for signing and provisioning your app:

  1. Installing them during the build
  2. Preinstalling them on a macOS build agent

Choose either of the tabs below for details.

Use this method when you do not have enduring access to the build agent, such as the hosted macOS agents. The P12 certificate and provisioning profile are installed at the beginning of the build and removed when the build completes.

Install the P12 certificate during your build

  1. Add the Install Apple Certificate task to your build before the Xcode or Xamarin.iOS task.
  2. Next to the Certificate (P12) field, click the settings icon and upload your P12 file to the Secure Files library. During upload, your certificate will be encrypted and securely stored.
  3. Once your certificate has been uploaded to the Secure Files library, select it in the Certificate (P12) dropdown.
  4. Go to the Variables tab and add a variable named P12password. Set its value to the password of your certificate. Be sure to click the lock icon. This will secure your password and obscure it in logs.
  5. Go back to the Tasks tab. In the Install Apple Certificate task's settings, reference your newly-created variable in the Certificate (P12) password field as: $(P12password)

Install the provisioning profile during your build

  1. Add the Install Apple Provisioning Profile task to your build before the Xcode or Xamarin.iOS task.
  2. For the Provisioning profile location option, choose Secure Files (in YAML, secureFiles).
  3. Next to the Provisioning profile field, click the settings icon and upload your provisioning profile file to the Secure Files library. During upload, your certificate will be encrypted and securely stored.
  4. Once your certificate has been uploaded to the Secure Files library, select it in the Provisioning profile dropdown.
  5. Enable the checkbox labeled Remove profile after build. This will ensure that the provisioning profile is not left on the agent machine.

Reference the files in your Xcode task

  1. Select the Xcode task.
  2. For the Signing style option, choose Manual signing.
  3. In the Signing identity field, enter $(APPLE_CERTIFICATE_SIGNING_IDENTITY). This variable is automatically set by the Install Apple Certificate task for the certificate you selected.
  4. In the Provisioning profile UUID field, enter $(APPLE_PROV_PROFILE_UUID). This variable is automatically set by the Install Apple Provisioning Profile task for the provisioning profile you selected.

Reference the files in your Xamarin.iOS task

  1. Select the Xamarin.iOS task.
  2. For the Override using option, choose Identifiers.
  3. In the Signing identity field, enter $(APPLE_CERTIFICATE_SIGNING_IDENTITY). This variable is automatically set by the Install Apple Certificate task for the certificate you selected.
  4. In the Provisioning profile UUID field, enter $(APPLE_PROV_PROFILE_UUID). This variable is automatically set by the Install Apple Provisioning Profile task for the provisioning profile you selected.

Save your build pipeline, and you are all set! The build agent will now be able to securely sign and provision your app.

Q & A

Do I need an agent?

You need at least one agent to run your build or release. Get an agent for Linux, macOS, or Windows.

I'm having problems. How can I troubleshoot them?

See Troubleshoot Build and Release.

I can't select a default agent pool and I can't queue my build or release. How do I fix this?

See Agent pools.

I use TFS on-premises and I don't see some of these features. Why not?

Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.