Obviously, the build machine has to be an OSX machine with XCode developer tools installed.
Certificates, Identities and Provisions must be installed on the build machine separately.
Just install the latest version of the plugin from the update center and configure a freestyle job (see #Usage Guide) that will use your OSX node (If your central instance isn't running under OSX).
If xcode related binaries aren't stored in the default location, update the global configuration of the plugin (Manage Jenkins -> Configure System)
Setting up a build step
Add the XCode build step to a free-style project and set the target (e.g.
MyApp), configuration (e.g.
Release) and check the build IPA and update version number options. This will give you a single, versioned .ipa file. You can also select to clean the project before a build; while this will make sure that the project is starting from a clean state, it will make large projects take a lot longer.
Setting up a unit test step
Add the XCode build step and this time specify your unit test target (e.g.
MyAppTests), configuration (e.g.
Debug) and the SDK (e.g.
Leave all the checkboxes unselected. The SDK needs to be supplied here as the unit tests will only be run when building under the simulator's SDK.
Check the "Publish JUnit test result report" option in the project config and set the value
*.xml" under "Test report XMLs". This will tell Jenkins to pick up the JUnit-format test reports.
XCode Builder configuration parameters
Clean before build?
This will delete the build directories before invoking the build. This will force the rebuilding of ALL dependencies and can make large projects take a lot longer.
The target to build. If left empty, this will build all targets in the project. If you wish to build your binary and the unit test module, it is best to do this as two separate steps each with their own target. This was, the iPhone Simulator SDK can be specified for the unit tests.
Xcode Schema File
Only needed if you want to compile for a specific schema instead of a target. It takes precedence over 'Xcode Configuration' setting and this job 'target' parameter.
You only need to supply this value if you want to specify the SDK to build against. If empty, the SDK will be determined by XCode. If you wish to run OCUnit tests, you will need to use the iPhone Simulator's SDK, for example:
You only need to supply this value if you want to specify the SYMROOT path to use. If empty, the default SYMROOT path will be used (it could be different depending of your Xcode version). Supports all macros and also environment and build variables from the Token Macro Plugin. For example you can use the value :
This is the name of the configuration as defined in the XCode project. By default there are Debug and Release configurations.
Custom xcodebuild arguments
Passing custom arguments is convenient when you need to change some project options for Jenkins build, but don't want them to persist in project file. For example when running application tests, following settings often are nice fit:
Xcode Workspace File
Only needed if you want to compile a workspace instead of a project. It takes precedence over 'Xcode Project File' setting and this job 'configuration' parameter."
Xcode Project Directory
This is the relative path from the workspace to the directory that contains the XCode project file. You only need to supply this value if the XCode project you wish to build is not in the root of the workspace.
Xcode Project File
If there is more than one XCode project file in the project path, you will need to specify the file name of the project you wish to build. If you need to build all project, you will need to create an XCode build step for each one manually.
Build output directory
The value to use for CONFIGURATION_BUILD_DIR setting (BUILD_DIR in >= 2.0.0). You only need to supply this value if you want the product of the XCode build to be in a location other than the one specified in project settings and this job 'SYMROOT' parameter. Supports all macros and also environment and build variables from the Token Macro Plugin. For example you can use the value :
This will set the
Clean test reports?
This will delete the processed test reports before invoking the build. Usually it is a good idea only to do it in test targets, otherwise if other Xcode target is built before tests – the build will fail to collect test reports.
Checking this option will create a .ipa for each .app found in the build directory. An .ipa is basically a zipped up .app. This is quite handy for distributing ad-hoc builds to testers as they can just double-click the .ipa and it will import into iTunes.
The relative path to the mobileprovision to embed, leave blank for no embedded profile.
Automatically unlock the keychain before signing the archive?
The path of the keychain to use to retrieve certificates to sign the package (default :
The password of the keychain to use to retrieve certificates to sign the package.
Using multiple versions of xcode.
One can easily support multiple versions by using environment variables. But first one need to install multiple versions on the build server. Here's one strategy:
install multiple versions of xcode
0. Note current config.
1. download xcode DMGs from http://developer.apple.com/downloads/
2. enable install from everywhere (under System preferences / Security)
Without that I had problems installing xcode, without graphical feedback, tested on 10.9.5, freshly booted.
- app not responsive
- Getting errors like in /var/log/system.log
Someone attempted to start application App:"Xcode" asn:0x0-1b62b61 pid:57656 refs=6 @ 0x7fa5d9f6df40 but it still has _kLSApplicationLockedInStoppedStateKey=true, so it is is staying stopped. : LASApplication.cp #2468 SetApplicationInStoppedState() q=LSSession 100027/0x186bb queue
3. open DMG file, copy app to /Applications. This might take a while.
4. close /Volumes/Xcode (otherwise installation won't start)
5. start Xcode, accept agreement, install missing packages if necessary. This might take a while. Close xcode after GUI opens.
6. move freshly installed Xcode to new path, e.g.
sudo mv /Applications/Xcode.app /Applications/Xcode6.1.app
(I use this so that the xcode app appears with version number under spotlight)
7. reset default xcode-select if necessary (installation might have changed it / reset to /Applications/Xcode.app)
sudo xcode-select -s /Applications/Xcode6.1.app
(Note the part above could be fully automated....)
Select the xcode version at runtime
1. Use EnvInject plugin
2. for jobs that require the non default do something like
under Inject environment variables to the build process
User interaction is not allowed
When code-signing, a prompt may appear on the build machine asking whether to allow keychain access.
This will block the build with a message like
"User interaction is not allowed" until it is dismissed.
Just select 'Always Allow' the first time and it shouldn't need to ask again.
If this prompt is not showing on the build machine, you can force it to appear by running the codesign command that failed from a terminal on the build machine: /usr/bin/codesign --force --sign "iPhone Distribution: .....
No Xcode folder is set
[sources] $ /usr/bin/xcodebuild -version xcode-select: Error: No Xcode folder is set. Run xcode-select -switch <xcode_folder_path> to set the path to the Xcode folder. Error: /usr/bin/xcode-select returned unexpected error. FATAL: Check your XCode installation. Jenkins cannot retrieve its version.
You probably just installed XCode (by default it is in
/Developer) but its path isn't configured. You can fix it with
xcode-select -switch /Developer/
You should now be able to execute
xcodebuild. Ex :
host:~ user$ /usr/bin/xcodebuild -version Xcode 4.2 Build version 4C199
XCode 4.3 changes 2 things that are important for our usage on a slave or a master :
- Command-Line Tools Are Optional : The command-line tools are not bundled with Xcode 4.3 by default. Instead, they have to be installed using the Components tab of the Downloads preferences panel
/Developer No Longer Exists : You may have to reconfigure its path like this:
sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer/
Version 2.0.0 (24th May 2017)
The plugin now requires Java 7 and Jenkins core >= 1.625.1
The plugin now requires Xcode >= 7
- New : Supports Xcode 7/8 (PR#76, PR#78, JENKINS-44203, JENKINS-44151, JENKINS-43226, JENKINS-43163, JENKINS-38799, JENKINS-38777, JENKINS-34307)
Replace 'xcrun PackageApplication' by 'xcodebuild -exportArchive' to package ipa
New Development Team parameter which can be configured globally in Jenkins Global settings or locally at the project level
- New : Adds Pipeline Plugin support (PR#74, JENKINS-42457, JENKINS-33355)
Version 1.4.11 (21th September 2016)
Because XXXX happens
- Fix: Support configurable ID for developer profile (JENKINS-32987)
Version 1.4.10 (20th September 2016)
- New: Support configurable ID for developer profile (JENKINS-32987)
- New: Allow the option not to sign the IPA with xcrun (JENKINS-32370)
- Fix: use textarea for Xcode Build Arguments (JENKINS-30228)
- Fix: Generating an archive builds the project twice (JENKINS-30362)
- Fix: Allowed the use of environment variables in plist url (JENKINS-27236)
Version 1.4.9 (23rd September 2015)
- Fix: only prepend -allTargets for -project builds (JENKINS-28256)
- New: Add support for Xcode 7 date format in Unit Testing build task (pull request xcode-plugin/63)
Version 1.4.8 (28th February, 2015)
- Fix: Add timeout to xcodebuild -list to avoid hang on xcode 6 (pull request xcode-plugin/58)
- New: Support multiple targets to be passed into xcodebuild (pull request xcode-plugin/43)
Version 1.4.7 (5th January, 2015)
- Fix: XCTest output parsing: support nested/namespaced test suites (JENKINS-26295)
- New: XCTest output parsing: handle tests suites exiting with an error (pull request xcode-plugin/54)
Version 1.4.6 (16th December, 2014)
- Fix: broken dSYM packaging (since 1.4.5)
- Fix: BUILD_DATE does not produce the correct last modified date if built on a slave machine (pull request xcode-plugin/50)
- Fix: make sure to set provideApplicationVersion properly upon upgrade from per-1.4.1 (JENKINS-26027)
- New: developerProfileLoader: use show-keychain-info to display job specific keychain information
- New: support XC test output (JENKINS-19955)
- New: display warning when simulator SDK selected and IPA about to be packaged (JENKINS-21293)
- New: document xcodebuildArguments (JENKINS-13930)
Version 1.4.5 (10th December, 2014)
- Fix: only zip the DSYM if the DSYM file was actually created and fail the build if the operation failed
- Fix: Fail the build if we fail to create an ipa.
- Fix: "keychain with the same name already exists" (JENKINS-22130)
- New: XCode 6 compatibility (pull request xcode-plugin/48)
- New: generate_manifest added ability to generate enterprise distribution manifest plist (pull request xcode-plugin/45)
- Fix: getKeychain returns a global keychain preferred over path (pull request xcode-plugin/41)
- New: Ability to change the Bundle identifier (CFBundleIdentifier) for an xcode build (pull request xcode-plugin/39)
Version 1.4.2 (31st December, 2013)
Version 1.4.1 (30th October, 2013)
Version 1.4 (2nd Oct, 2013)
- New: added an option to produce .xcarchive (JENKINS-14719)
- Fix: Fixing show-keychain-info call (JENKINS-xcode-plugin/30)
- New: Build wrapper to restore the keychain at the end of the build (pull request xcode-plugin/31)
- New: Adding the possibility to provide a pattern for the .ipa file name (pull request xcode-plugin/33)
- New: Added an ability to import *.developerprofile into a build (pull request xcode-plugin/34)
- New: UI update: group options into 3 categories (pull request xcode-plugin/28)
- New: Introduced the ability to create global keychain configurations
- New: Add new option "allow failing build results" (pull request xcode-plugin/25)
- Fix: xcodebuild output parser is more lenient (pull request xcode-plugin/19)
- Fix: Can't add xcodebuild parameters including whitespace (JENKINS-12800)
- New: Add a field for entering code signing identity (pull request xcode-plugin/6)
Version 1.3.1 (27th March 2012)
- Fix: Custom xcodebuild arguments values are not persisted (JENKINS-12510).
Version 1.3 (20th January 2012)
- New : Ability to specify custom arguments to xcodebuild (so that values in project file can be overridden). It is needed to specify custom build options to make in-app unit tests work.
- New : Ability to disable clean up of test reports on per-target level, so that it is possible to run several targets in single job and not mess-up test reports.
- Fix : The plugin fails by searching for a double .app extension while compressing .dsym (JENKINS-12273)
- Fix : The plugin fails to delete previous generated IPA results in a failed build (JENKINS-12237).
- Fix : The plugin fails to set default keychain when using an alternate (non login) keychain (By default the login keychain is the default keychain) (JENKINS-12217).
- Fix : Restore Java 1.5 runtime compatibility. (JENKINS-12378)
Version 1.2.2 (19th December 2011)
- Fix : Build IPA fails if the plugin is launched on a remote agent using a relative path for its FS Root directory (JENKINS-12144)
Version 1.2.1 (18th December 2011)
- Fix : Build IPA switch doesn't work properly for a default Xcode project always results in FATAL error (JENKINS-12089)
Version 1.2 (8th December 2011)
- New build parameter to specify the build output directory. This overrides the setting in the user's project file, so it will be put into a known directory rather than XcodeDerivedData, etc. This makes it much easier to set up subsequent build steps in Jenkins that do something with the output of the build. It does this by passing the setting CONFIGURATION_BUILD_DIR to xcodebuild if a path is set for this new job config value.
- Add support for building schemes and workspaces : The plugin now supports two extra configuration parameters
xcodeWorkspaceFile. The scheme maps to xcodebuild's parameter "-scheme" and the workspace to "-workspace". The scheme takes precedence over the target setting and the workspace takes precedence over the project setting.
Version 1.1 (29th November 2011)
- Upgrade the token macro plugin to version 1.5.1 to support environment and build variables (JENKINS-11892)
- New configuration parameter to set the SYMROOT value passed to the build. This parameter accepts environment and build variables and Macros (JENKINS-11813)
- Various code cleanup and improvements.
Version 1.0.1 (14th November 2011)
- Minor fix about the default value and the documentation of the keystore path parameter.
Version 1.0 (14th November 2011)
- Initiated from Ray Yamamoto Hilton's Xcode plugin for Hudson with few changes :
- It improves jenkins compatibility, and is available in its update center.
- It uses the Token Macro Plugin to configure values of
- It allows to configure the keychain to use and to unlock it
- It is ready for internationalization
If you previously used the version provided by Ray you should be able to test this one in parallel as it has a new identity. Also you'll have to reconfigure a large part of it if you want to upgrade thus don't forget to save your settings.