Build your Xcode app

VSTS | TFS 2017 Update 2

Visual Studio Team Services (VSTS) and Team Foundation Server (TFS) provide a highly customizable continuous integration (CI) process to automatically build and package your Xcode app whenever your team pushes or checks in code. In this quickstart you learn how to define your CI process.

Prerequisites

  • A VSTS account. If you don't have one, you can create one for free. If your team already has one, then make sure you are an administrator of the team project you want to use.
  • While the simplest way to try this quickstart is to use a VSTS account, you can also use a TFS server instead of a VSTS account.

  • You need a build agent configured on a Mac machine. Simply open the OSX Terminal app on your Mac and follow these setup instructions. The agent will automatically register itself with VSTS / TFS when you start up the agent for the first time.

  • Your Mac also needs to have Node.js, Xcode, and xcpretty (for testing) installed.

Get the sample code

To configure a CI build process for your app, the source code needs to be in a version control system. VSTS and TFS integrate with various version control systems such as Git in VSTS or TFS, Team Foundation Version Control (TFVC), GitHub, and Subversion.

For a simple way to follow this quickstart, get the following sample app code and put it into your own version control repository:

https://github.com/adventworks/xcode-sample

To import the sample app into a Git repo in VSTS or TFS:

  1. On the Code hub for your team project in VSTS/TFS, select the option to Import repository.

  2. In the Import a Git repository dialog box, paste the above URL into the Clone URL text box.

  3. Click Import to copy the sample code into your Git repo.

The sample provided here is an iOS app, but the concepts described here essentially translate to other Xcode builds. Results from running tests are published to VSTS using xcpretty. That is why you will need to have xcpretty installed on the OSX machine as this is not part of Xcode itself.

Set up continuous integration

A continuous integration (CI) process automatically builds and tests code every time a team member commits changes to version control. Here you'll create a CI build definition that helps your team keep the master branch clean.

  1. Create a new build definition.

    Navigate to the Files tab of the Code hub, and then click Set up build.

    Screenshot showing button to set up build for a repository

    You are taken to the Build & Release hub and asked to Select a template for the new build definition.

  2. In the right panel, click Xcode, and then click Apply.

    You now see all the tasks that were automatically added to the build definition by the template. These are the steps that will automatically run every time you check in code.

  3. For the Default agent queue, select a queue that includes the Mac agent you set up.

  4. Click Get sources and then:

    Observe that the new build definition is automatically linked to your repository.

  5. Set the following parameters for the Xcode test task:

    • Scheme: Name of the scheme shared.
    • Advanced > Create App Package: Unchecked.
    • Advanced > Use xcpretty: Checked.
    • Advanced > Xcode Developer Path: allows you to specify the path of a different version of Xcode than is installed by default. Ex: /Applications/Xcode6.4.app/Contents/Developer.

    Troubleshooting Tip: The "Release" configuration is not testable by default. You'll either need to use "Debug" or enable testability in for the configuration in Xcode. Also, be sure to pay attention to capitalization as "Debug" will work but "debug" may not.

  6. Set the following parameters for the Xcode build task:

    • Scheme: Name of the scheme shared.
  7. On the Variables tab in the build definition, add the following variables:

    • Configuration: Debug or Release
    • SDK: iphoneos
    • TestSDK: iphonesimulator
  8. Click the Triggers tab in the build definition. Enable the Continuous Integration trigger. This will ensure that the build process is automatically triggered every time you commit a change to your repository.

  9. Click Save and queue to kick off your first build. On the Queue build dialog box, click Queue.

  10. A new build is started. You'll see a link to the new build on the top of the page. Click the link to watch the new build as it happens.

    Troubleshooting Tip: If you encounter a "User interaction not allowed" error when running the agent as a launch agent, you will either need check the "Unlock default keychain" option or switch to referencing signing certificates using a file. See Simple, Secure CI App Signing for details.

    Troubleshooting Tip: If you run into issues with your tests hanging and/or not being able to start the iOS Simulator at times you can opt to add a Command Line task for the "killall" tool with "iOS\ Simulator" as an argument (killall iOS\ Simulator). This will force shut down the simulator in the event it is hung. Exercise care when running the command if you have multiple agents running for the same user and that you do not accidently kill other processes.

View the build summary

  1. Once the build completes, select the build number to view a summary of the build.

    Navigate to build summary

  2. Notice the various sections in the build summary - the source version of the commit in build details section, list of all associated changes, links to work items associated with commits, and test results. When the build is automatically triggered by a push to your Git repository, these sections are populated with all the relevant information.

Next steps

If you plan to use your own Xcode project for this quickstart, there is really only one additional step required for configuring the project for a CI environment that is not done by default when you create the Xcode project. Xcode has the concept of schemes and you'll need to set one of these as "Shared" and add it to source control so it can be used during your CI builds. Follow these steps:

  1. In Xcode, open your project and go to Product Scheme Manage Schemes...

  2. Check Shared next to the Scheme you want to use during CI. Remember the name of the scheme you shared as we will reference it later.

  3. Now add the new files and folders in your .xcodeproj folder (specifically the xcsharedata folder to source control).

    Shared Scheme

To sign your application with a certificate as part of CI, see How to: Secure Xcode App.