Build: Xcode

VSTS | TFS 2018 | TFS 2017 | TFS 2015

icon Build, test, or archive an Xcode workspace on macOS. Optionally package an app.

Demands

xcode

YAML snippet

# Xcode
# Build, test, or archive an Xcode workspace on macOS. Optionally package an app.
- task: Xcode@5
  inputs:
    #actions: 'build' 
    #configuration: '$(Configuration)' # Optional
    #sdk: '$(SDK)' # Optional
    #xcWorkspacePath: '**/*.xcodeproj/project.xcworkspace' # Optional
    #scheme: # Optional
    #xcodeVersion: 'default' # Optional. Options: 8, 9, default, specifyPath
    #xcodeDeveloperDir: # Optional
    packageApp: 
    #archivePath: # Optional
    #exportPath: 'output/$(SDK)/$(Configuration)' # Optional
    #exportOptions: 'auto' # Optional. Options: auto, plist, specify
    #exportMethod: 'development' # Required when exportOptions == Specify
    #exportTeamId: # Optional
    #exportOptionsPlist: # Required when exportOptions == Plist
    #exportArgs: # Optional
    #signingOption: 'nosign' # Optional. Options: nosign, default, manual, auto
    #signingIdentity: # Optional
    #provisioningProfileUuid: # Optional
    #provisioningProfileName: # Optional
    #teamId: # Optional
    #destinationPlatformOption: 'default' # Optional. Options: default, iOS, tvOS, macOS, custom
    #destinationPlatform: # Optional
    #destinationTypeOption: 'simulators' # Optional. Options: simulators, devices
    #destinationSimulators: 'iPhone 7' # Optional
    #destinationDevices: # Optional
    #args: # Optional
    #workingDirectory: # Optional
    #useXcpretty: # Optional
    #publishJUnitResults: # Optional

Arguments

Argument Description
Actions Enter a space-delimited list of actions. Valid options are build, clean, test, analyze, and archive. For example, clean build will run a clean build. See the xcodebuild man page.
Configuration Enter the Xcode project or workspace configuration to be built. The default value of this field is the variable $(Configuration). When using a variable, make sure to specify a value (for example, Release) on the Variables tab.
SDK Specify an SDK to use when building the Xcode project or workspace. From the macOS Terminal application, run xcodebuild -showsdks to display the valid list of SDKs. The default value of this field is the variable $(SDK). When using a variable, make sure to specify a value (for example, iphonesimulator) on the Variables tab.
Workspace or project path (Optional) Enter a relative path from the root of the repository to the Xcode workspace or project. For example, MyApp/MyApp.xcworkspace or MyApp/MyApp.xcodeproj.
Scheme (Optional) Enter a scheme name defined in Xcode. It must be a shared scheme, with its Shared checkbox enabled under Managed Schemes in Xcode. If you specify a Workspace or project path above without specifying a scheme, and the workspace has a single shared scheme, it will be automatically used.
Xcode version Specify the target version of Xcode. Select Default to use the default version of Xcode on the agent machine. Selecting a version number (e.g. Xcode 9) relies on environment variables being set on the agent machine for the version's location (e.g. XCODE_9_DEVELOPER_DIR=/Applications/Xcode_9.0.0.app/Contents/Developer). Select Specify path to provide a specific path to the Xcode developer directory.
Xcode developer path (Optional) Enter a path to a specific Xcode developer directory (e.g. /Applications/Xcode_9.0.0.app/Contents/Developer). This is useful when multiple versions of Xcode are installed on the agent machine.
(Optional) Signing & provisioning
Signing style Choose the method of signing the build. Select Do not code sign to disable signing. Select Project defaults to use only the project's signing configuration. Select Manual signing to force manual signing and optionally specify a signing identity and provisioning profile. Select Automatic signing to force automatic signing and optionally specify a development team ID. If your project requires signing, use the "Install Apple..." tasks to install certificates and provisioning profiles prior to the Xcode build.
Signing identity (Optional) Enter a signing identity override with which to sign the build. This may require unlocking the default keychain on the agent machine. If no value is entered, the Xcode project's setting will be used.
Provisioning profile UUID (Optional) Enter the UUID of an installed provisioning profile to be used for this build. Use separate build tasks with different schemes or targets to specify separate provisioning profiles by target in a single workspace (iOS, tvOS, watchOS).
Team ID (Optional, unless you are a member of multiple development teams.) Specify the 10-character development team ID.
Package options
Create app package Indicate whether an IPA app package file should be generated as a part of the build.
Archive path (Optional) Specify a directory where created archives should be placed.
Export path (Optional) Specify the destination for the product exported from the archive.
Export options Select a way of providing options for exporting the archive. When the default value of Automatic is selected, the export method is automatically detected from the archive. Select Plist to specify a plist file containing export options. Select Specify to provide a specific Export method and Team ID.
Export method Enter the method that Xcode should use to export the archive. For example: app-store, package, ad-hoc, enterprise, or development.
Team ID (Optional) Enter the 10-character team ID from the Apple Developer Portal to use during export.
Export options plist Enter the path to the plist file that contains options to use during export.
Export arguments (Optional) Enter additional command line arguments to be used during export.
Devices & simulators
Destination platform Select the destination device's platform to be used for UI testing when the generic build device isn't valid. Choose Custom to specify a platform not included in this list. When Default is selected, no simulators nor devices will be targeted.
Destination type Choose the destination type to be used for UI testing. Devices must be connected to the Mac performing the build via a cable or network connection. See Devices and Simulators in Xcode.
Simulators Enter an Xcode simulator name to be used for UI testing. For example, enter iPhone X (iOS and watchOS) or Apple TV 4K (tvOS). A target OS version is optional and can be specified in the format 'OS=versionNumber', such as iPhone X,OS=11.1. A list of simulators installed on the Hosted macOS agent can be found here.
Devices Enter the name of the device to be used for UI testing, such as Raisa's iPad. Only one device is currently supported. Note that Apple does not allow apostrophes (') in device names. Instead, right single quotation marks (') can be used.
Advanced
Arguments (Optional) Enter additional command line arguments with which to build. This is useful for specifying -target or -project arguments instead of specifying a workspace/project and scheme. See the xcodebuild man page.
Working directory (Optional) Enter the working directory in which to run the build. If no value is entered, the root of the repository will be used.
Output directory Enter a path relative to the working directory where build output (binaries) will be placed. The default value includes variables. When these are used, make sure to specify values on the Variables tab.
Use xcpretty Specify whether to use xcpretty to format xcodebuild output and generate JUnit test results. Enabling this requires xcpretty to be installed on the agent machine. It is preinstalled on VSTS hosted build agents. See xcpretty on GitHub.
Publish test results to VSTS/TFS If xcpretty is enabled above, specify whether to publish JUnit test results to VSTS/TFS.
Control options

Example

Build your Xcode app

Open source

This task is open source on GitHub. Feedback and contributions are welcome.

Q & A

Do I need an agent?

You need at least one agent to run your build or release. Get an agent.

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

See Agent pools and queues.