Xcode integration

This plugin adds the ability to call Xcode command line tools to automate build and packaging iOS applications (iPhone, iPad, ...).

• Report all issues or features requests in Jira : https://issues.jenkins-ci.org/issues/?jql=component%20%3D%20xcode-plugin

Contact the Jenkins Community by mail or irc to have support.

The maintainer is looking for a co-maintainer. I need your help!!

To help us maintain the plugin, you can take contact to jerome.lacoste at gmail.com in particular if you are able to test upcoming releases

Thank you!

A problem, An idea ?

Please use our tasks and issues tracker to report bugs, improvements or new feature.

• Report a bug
• Ask for a new feature
• Ask for an improvement of an existing feature

Also if you want to propose some code change using a Github pull request, please open also a Jira issue. It is easier for developers to track them.

Important!

Newesth version is compatibility with the previous version priour 2.0.12 is maintained. However, major changes have been made to the handling of macOS keychains.

Information to access the keychain is moved from configuration to credentials.
After that, the information for accessing the keychain must be registered in the credentials.

This plugin adds the ability to call Xcode command line tools to automate build and packaging iOS applications (iPhone, iPad, ...).

This builder can invoke agvtool to dynamically update the CFBundleVersion (a.k.a. Technical Version) or CFBundleShortVersionString (a.k.a. Marketing Version). It supports all macros from the . For example the value ${BUILD_NUMBER} will be replaced with the current build number. We advice you to generate a unique value for each build for the CFBundleVersion if you want for example deploy it into a private store. In that case you can use for example : ${JOB_NAME}-${BUILD_NUMBER}

The target (optional), configuration (e.g. Debug, Release) and SDK (optional) can be specified in the per-project config along with whether to perform a clean before the build phase.

The builder can be used to package the .app into a .ipa. Since a .app is actually a directory, it can be awkward to work with and, especially, distribute. We can simplify this by packaging the .app into a single .ipa file, which is just a
zip file with a well-known internal structure

This plugin has two features that help you simplify the code signing process.

This plugin builds on top of to allow you to store your Apple Developer Profile (*.developerprofile) file. This file contains a code signing private key, corresponding developer/distribution certificates, and mobile provisioning profiles. You can create this file from your XCode.

To upload the developer profile into Jenkins, go to "Manage Credentials" in the system configuration page, and select "Apple Developer Profile" from the "Add" button. See for further details.

To use this profile for signing, add "Import developer profile" as a build step before you run xcode, and select the developer profile to import into the build machine. This build step will install the developer profile into the slave's keychain.

If you create a dedicated keychain that stores the code signing private key and certificate on every build slave, you can configure the plugin to just unlock this keychain (so that xcode can use it for signing)

Unlocking

If you store your keys in the user keychain (most probably) and if you run jenkins as daemon, make sure you installed a recent version of jenkins for Mac, or configured the daemon to create a session (through the CreationSession=true parameter in your org.jenkins-ci.plist daemon config file). See also

Timeouts

The keychain has a default timeout of 300 seconds. One can override it using the security set-keychain-settings command, which isn't supported in the plugin today. Support in the plugin could be improved by adding options to modify the timeout as part of the build process. See JENKINS-17184.

This plugin will listen to the xcodebuild output when running OCUnit or XC tests and write out JUnit-format test reports that Jenkins can understand. Jenkins will then use these to publish test failure reports and graphs.

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)

If you want to use multiple versions of Xcode to build your application, use ’Global Tool Configuration’ to register the distinguished name and location of the installed Xcode.

By adding the Import developer profile step to Build, you can import developer profiles exported to Xcode into temporary keychains or existing keychains.
The developer profile contains a set of certificates, secret keys and provisioning profiles necessary for compiling and signing applications, which is useful for distributing with multiple Jenkins nodes.

Limitations

The Xcode Integration Plugin has the function of importing the secret key and certificate of the developer account into the temporary key chain, but as the constraint of macOS can not handle different key chain for each session, the job handling the key chain If you execute them in parallel, this will not work properly.

As one of workarounds, it is impossible to limit the maximum number of jobs around Jenkins' node to 1 and to execute multiple nodes with different macOS accounts.

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.

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. Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator4.1.sdk/).
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 "*``/test-reports/``*.xml" under "Test report XMLs". This will tell Jenkins to pick up the JUnit-format test reports.

If you add the Export IPA step and set up the information necessary for exporting the IPA file, the location of the archive, the export method, code signature information, etc., you can export the IPA from the archive output in the Xcode Build step.

1. Import developer profile.

           importDeveloperProfile(importIntoExistingKeychain: false,
               profileId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')
   

2. Build the project and output the archive.

           xcodeBuild(
             xcodeSchema: "${PROJECT_SCHEMA}",
             ipaOutputDirectory: 'Release',
             ipaExportMethod: 'app-store',
             generateArchive: true,
             buildIpa: true,
             ipaName: "${BUILD_TARGET}",
             bundleID: 'com.example.TargetApp',
             developmentTeamName: "${DEVELOPMENT_TEAM_NAME}",
             cleanBeforeBuild: true,
             configuration: 'Release',
             cfBundleShortVersionStringValue: '1.0.0',
             cfBundleVersionValue: '1'
           )
   

3. Export the IPA file from the archive.

       exportIpa(
           archiveDir: "${WORKSPACE}/${repositoryName}/build/Release-iphoneos",
           xcodeSchema: "${PROJECT_SCHEMA}",
           developmentTeamName: "${DEVELOPMENT_TEAM}",
           configuration: "AdHoc",
           infoPlistPath: "${INFO_PLIST}",
           manualSigning: true,
           provisioningProfiles: [
               [provisioningProfileAppId: "${BUNDLE_ID}", provisioningProfileUUID: 'TestApp_AdHoc_Profile.mobileprovision']
               [provisioningProfileAppId: "${BUNDLE_ID}.watchkitapp", provisioningProfileUUID: 'TestApp_AdHoc_Profile.mobileprovision'],
               [provisioningProfileAppId: "${BUNDLE_ID}.watchkitapp.watchkitextension", provisioningProfileUUID: 'TestApp_AdHoc_Profile.mobileprovision']
           ],
           ipaExportMethod: "ad-hoc",
           ipaName: "${BUILD_TARGET}",
           ipaOutputDirectory: "AdHoc"
       )
   

4. Upload the exported IPA file.

When using "XCode's" Automatically manage signing ", various ways are required, so please note the points to be noted separately.

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:

0. Note current config.

xcode-select -p

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.

Symptoms were:

• 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....)

1. Use EnvInject plugin
2. for jobs that require the non default do something like

DEVELOPER_DIR=/Applications/Xcode6.0.1.app/Contents/Developer

under Inject environment variables to the build process

1. Register the distinguished name and location of the installed Xcode using ’Global Tool Configuration’.
2. Select Xcode registered in 'Global Tool Configuration' in Job's 'Xcode Tools Version'.

That's it.

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: .....

[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/