Xcode@4 - Xcode v4 task
Use this task to build, test, or archive an Xcode workspace on macOS, and optionally package an app.
Syntax
# Xcode v4
# Build, test, or archive an Xcode workspace on macOS. Optionally package an app.
- task: Xcode@4
inputs:
actions: 'build' # string. Required. Actions. Default: build.
#configuration: '$(Configuration)' # string. Configuration. Default: $(Configuration).
#sdk: '$(SDK)' # string. SDK. Default: $(SDK).
#xcWorkspacePath: '**/*.xcodeproj/project.xcworkspace' # string. Workspace or project path. Default: **/*.xcodeproj/project.xcworkspace.
#scheme: # string. Scheme.
#xcodeVersion: 'default' # '8' | '9' | 'default' | 'specifyPath'. Xcode version. Default: default.
#xcodeDeveloperDir: # string. Optional. Use when xcodeVersion == specifyPath. Xcode developer path.
# Package options
#packageApp: false # boolean. Create app package. Default: false.
#archivePath: # string. Optional. Use when packageApp == true. Archive path.
#exportPath: 'output/$(SDK)/$(Configuration)' # string. Optional. Use when packageApp == true. Export path. Default: output/$(SDK)/$(Configuration).
#exportOptions: 'auto' # 'auto' | 'plist' | 'specify'. Optional. Use when packageApp == true. Export options. Default: auto.
#exportMethod: 'development' # string. Required when exportOptions == specify. Export method. Default: development.
#exportTeamId: # string. Optional. Use when exportOptions == specify. Team ID.
#exportOptionsPlist: # string. Required when exportOptions == plist. Export options plist.
#exportArgs: # string. Optional. Use when packageApp == true. Export arguments.
# Signing & provisioning
#signingOption: 'nosign' # 'nosign' | 'default' | 'manual' | 'auto'. Signing style. Default: nosign.
#signingIdentity: # string. Optional. Use when signingOption = manual. Signing identity.
#provisioningProfileUuid: # string. Optional. Use when signingOption = manual. Provisioning profile UUID.
#teamId: # string. Optional. Use when signingOption = auto. Team ID.
# Devices & simulators
#destinationPlatformOption: 'default' # 'default' | 'iOS' | 'tvOS' | 'macOS' | 'custom'. Destination platform. Default: default.
#destinationPlatform: # string. Optional. Use when destinationPlatformOption == custom. Custom destination platform.
#destinationTypeOption: 'simulators' # 'simulators' | 'devices'. Optional. Use when destinationPlatformOption != default && destinationPlatformOption != macOS. Destination type. Default: simulators.
#destinationSimulators: 'iPhone 7' # string. Optional. Use when destinationPlatformOption != default && destinationPlatformOption != macOS && destinationTypeOption == simulators. Simulator. Default: iPhone 7.
#destinationDevices: # string. Optional. Use when destinationPlatformOption != default && destinationPlatformOption != macOS && destinationTypeOption == devices. Device.
# Advanced
#args: # string. Arguments.
#workingDirectory: # string. Alias: cwd. Working directory.
#outputPattern: # string. Output directory.
#useXcpretty: false # boolean. Use xcpretty. Default: false.
#publishJUnitResults: false # boolean. Publish test results to VSTS/TFS. Default: false.
Inputs
actions - Actions
string. Required. Default value: build.
Specifies a space-delimited list of actions. Valid options are build, clean, test, analyze, and archive. For example,clean build performs a clean build. See the Apple: Building from the command line with Xcode FAQ.
configuration - Configuration
string. Default value: $(Configuration).
Specifies the Xcode project or workspace configuration to build. When using a variable, specify a value (for example, Release) on the Variables tab.
sdk - SDK
string. Default value: $(SDK).
Specifies 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. When using a variable, specify a value (for example, iphonesimulator) on the Variables tab.
xcWorkspacePath - Workspace or project path
string. Default value: **/*.xcodeproj/project.xcworkspace.
Optional. Specifies a relative path from the root of the repository to the Xcode workspace or project. If you specify a value, you must also specify the scheme. Do not specify a value if you are specifying -target flag in Advanced Arguments. For example, MyApp/MyApp.xcworkspace or MyApp/MyApp.xcodeproj.
scheme - Scheme
string.
Optional. Specifies an Xcode scheme name. Must be a shared scheme (shared checkbox under Managed Schemes in Xcode). If you do not specify a scheme, and the specified workspace has a single shared scheme, the workspace scheme will be used.
xcodeVersion - Xcode version
string. Allowed values: 8 (Xcode 8), 9 (Xcode 9), default, specifyPath (Specify path). Default value: default.
Specifies the target version of Xcode. Select Default to use the default version of Xcode on the agent machine. Specifying a version number (for example, Xcode 9) relies on the version's location to be set by environment variables on the agent machine (for example, 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.
xcodeDeveloperDir - Xcode developer path
string. Optional. Use when xcodeVersion == specifyPath.
Specifies a path to a specific Xcode developer directory (for example, /Applications/Xcode_9.0.0.app/Contents/Developer). This input is useful when multiple versions of Xcode are installed on the agent machine.
packageApp - Create app package
boolean. Default value: false.
Specifies whether an IPA app package file should be generated as a part of the build.
archivePath - Archive path
string. Optional. Use when packageApp == true.
Specifies a directory where created archives are placed.
exportPath - Export path
string. Optional. Use when packageApp == true. Default value: output/$(SDK)/$(Configuration).
Specifies the destination for the product exported from the archive.
exportOptions - Export options
string. Optional. Use when packageApp == true. Allowed values: auto (Automatic), plist, specify. Default value: auto.
Specifies 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.
exportMethod - Export method
string. Required when exportOptions == specify. Default value: development.
Specifies the method that Xcode uses to export the archive. For example: app-store, package, ad-hoc, enterprise, or development.
exportTeamId - Team ID
string. Optional. Use when exportOptions == specify.
Specifies the Apple Developer Portal 10-character team ID to use during the export.
exportOptionsPlist - Export options plist
string. Required when exportOptions == plist.
Specifies the path to the plist file that contains options to use during the export.
exportArgs - Export arguments
string. Optional. Use when packageApp == true.
Specifies additional command line arguments used during the export.
signingOption - Signing style
string. Allowed values: nosign (Do not code sign), default (Project defaults), manual (Manual signing), auto (Automatic signing). Default value: nosign.
Specifies 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.
signingIdentity - Signing identity
string. Optional. Use when signingOption = manual.
Specifies a signing identity override with which to sign the build. Unlocking the default keychain on the agent machine may be required. If no value is entered, the Xcode project's setting is used.
provisioningProfileUuid - Provisioning profile UUID
string. Optional. Use when signingOption = manual.
Specifies the UUID of an installed provisioning profile used for the build. Use separate build tasks with different schemes or targets to specify provisioning profiles by target in a single workspace (iOS, tvOS, watchOS).
teamId - Team ID
string. Optional. Use when signingOption = auto.
Required if you are a member of multiple development teams. Specifies the 10-character development team ID.
destinationPlatformOption - Destination platform
string. Allowed values: default, iOS (iOS and watchOS), tvOS, macOS, custom. Default value: default.
Specifies the destination device's platform used for UI testing when the generic build device isn't valid. Choose Custom to specify a platform not included in the list. When Default is selected, no simulators or devices are targeted.
destinationPlatform - Custom destination platform
string. Optional. Use when destinationPlatformOption == custom.
Specifies a destination device's platform used for UI testing when the generic build device isn't valid.
destinationTypeOption - Destination type
string. Optional. Use when destinationPlatformOption != default && destinationPlatformOption != macOS. Allowed values: simulators (Simulator), devices (Connected Device). Default value: simulators.
Specifies the destination type 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 for more information.
destinationSimulators - Simulator
string. Optional. Use when destinationPlatformOption != default && destinationPlatformOption != macOS && destinationTypeOption == simulators. Default value: iPhone 7.
Specifies an Xcode simulator name used for UI testing. For example, iPhone X (iOS and watchOS) or Apple TV 4K (tvOS). An optional target OS version can be specified in the format OS=<versionNumber>, such as iPhone X,OS=11.1. Learn more about installed simulators on the Hosted macOS Preview agent.
destinationDevices - Device
string. Optional. Use when destinationPlatformOption != default && destinationPlatformOption != macOS && destinationTypeOption == devices.
Specifies the name of the device used for UI testing, such as Raisa's iPad.
args - Arguments
string.
Optional. Specifies additional command line arguments with which to build. This input is useful for specifying -target or -project arguments instead of a workspace/project and scheme. See the Apple: Building from the command line with Xcode FAQ.
workingDirectory - Working directory
Input alias: cwd. string.
Optional. Specifies the working directory in which to run the build. If no value is entered, the root of the repository is used.
outputPattern - Output directory
string.
Optional. Specifies a relative path to the working directory where build output (binaries) are placed. For example: output/$(SDK)/$(Configuration) or output/$(TestSDK)/$(TestConfiguration). Archive and export paths are configured separately. Specify values on the Variables tab.
useXcpretty - Use xcpretty
boolean. Default value: false.
Specifies whether to use xcpretty to format xcodebuild output, and generates JUnit test results. xcpretty must be installed on the agent machine (It is preinstalled on VSTS hosted build agents). See xcpretty for more information.
publishJUnitResults - Publish test results to VSTS/TFS
boolean. Default value: false.
If xcpretty is enabled, this input specifies whether to publish the JUnit test results to VSTS/TFS.
Task control options
All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.
Output variables
None.
Remarks
Use this task to build an Xcode workspace on macOS.
Examples
Requirements
| Requirement | Description |
|---|---|
| Pipeline types | YAML, Classic build |
| Runs on | Agent, DeploymentGroup |
| Demands | Self-hosted agents must have capabilities that match the following demands to run jobs that use this task: xcode |
| Capabilities | This task does not satisfy any demands for subsequent tasks in the job. |
| Command restrictions | Any |
| Settable variables | Any |
| Agent version | All supported agent versions. |
| Task category | Build |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for