https://github.com/roblabs/xcode-continuous-integration
CI scripts for use in Xcode Continuous Integration *bots* 🤖. Also useful for manual builds.
https://github.com/roblabs/xcode-continuous-integration
ci continuous-integration xcode xcode-bots xcode-server xcs
Last synced: 18 days ago
JSON representation
CI scripts for use in Xcode Continuous Integration *bots* 🤖. Also useful for manual builds.
- Host: GitHub
- URL: https://github.com/roblabs/xcode-continuous-integration
- Owner: roblabs
- License: mit
- Archived: true
- Created: 2020-09-19T19:44:39.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-04-11T20:21:39.000Z (about 2 years ago)
- Last Synced: 2025-04-06T08:37:04.161Z (24 days ago)
- Topics: ci, continuous-integration, xcode, xcode-bots, xcode-server, xcs
- Language: Shell
- Homepage: https://RobLabs.com/xcode
- Size: 71.3 KB
- Stars: 12
- Watchers: 1
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Xcode Server Bots 🤖 and Continuous Integration Guide
Goal — ***one button Xcode builds*** with Xcode Server or `XCS`
Do you have CI or *Continuous Integration* for your applications built with Xcode? There are plenty to choose from and they have their advantages. But consider Xcode Server *Bots* built directly into Xcode: there is nothing to install and your project can be up and running in a matter of minutes.
We all want simple builds. If you are able to check your code into a `git` repo, then it should be able to `git pull` and build in small number of steps. If you can minimize the number of dependencies to be installed or to be `fetch`ed, then your builds will be more repeatable. More repeatable; possibly better quality. More repeatable; prime for automation with Xcode Server *Bots*.
Many Open Source Xcode projects already have a CI architecture. But if you want to learn the code or achieve ***one button Xcode builds***, then you would have to install or learn a new dependency. Xcode Server Bots can still be used in this case.
The Xcode Server Bots documentation makes the compelling case to use Bots. The documentation on [Continuous integration using Xcode Server](https://help.apple.com/xcode/mac/11.4/index.html?localePath=en.lproj#/dev466720061) from Apple is the best resource for setting up your Xcode Server Bots.
> In Xcode, continuous integration is the process of automating and streamlining the building, analyzing, testing, and archiving of your Mac and iOS apps, in order to ensure that they are always in a releasable state. [1]
> The goal of continuous integration is to improve software quality, and there are a number of ways this is achieved:
> * Catching problems quickly, easily, and early.
> * Enhancing collaboration.
> * Broadening test coverage.
> * Generating build and test statistics over time.
* [1] : https://developer.apple.com/library/archive/documentation/IDEs/Conceptual/xcode_guide-continuous_integration/index.html
* [2] : https://developer.apple.com/search/?q=xcode%20server&type=Videos
* [Xcode Server Environment Variable Reference](https://developer.apple.com/library/archive/documentation/IDEs/Conceptual/xcode_guide-continuous_integration/EnvironmentVariableReference.html)
* [Xcode Server API Reference](https://developer.apple.com/library/archive/documentation/Xcode/Conceptual/XcodeServerAPIReference/Bots.html)
* [Verify, reveal, and delete installed toolchains]: https://help.apple.com/xcode/mac/11.4/index.html?localePath=en.lproj#/dev128b6c856 "Verify, reveal, and delete installed toolchains"
This repo includes CI scripts for use in Xcode Continuous Integration *Bots*. Also useful for manual builds. Support for `carthage` for fetching binaries. If you CocoaPods, you can still use this repo. It's likely you can still use this as you will likely be using the CocoaPods `.xcworkspace`, which this can still be integrated into.
#### Add as a `git submodule`
Add this repo as a `git submodule`. The directory name it creates will be `xcode-continuous-integration` and the shell scripts will be in that directory.
```
# Add repo to the current directory
git submodule add https://github.com/roblabs/xcode-continuous-integration.git
```
#### In Xcode Schemes
`Edit Scheme` > `Build` > `Pre-Actions` > `Run Script` > Add the following (assuming the proper path relative to your `${PROJECT_DIR}`)
```
cd ${PROJECT_DIR}
git submodule update --init --recursive
wait
sh ${PROJECT_DIR}/xcode-continuous-integration/ci.sh
```
---
---
#### In Xcode Server Bots
Let's take the special case of building Mapbox GL Native for iOS. See the `examples` folder for scripts for setting up `XCS` with
* `mapbox-gl-native-ios`, versions <= v5.9
* `mapbox-gl-native-ios`, versions > 6.0
1. The Git branch and Xcode scheme you want to test is very important, so check out a local copy to your development folder. For example, set the branch you want and perform the initial step to make the Xcode Project.
`mapbox-gl-native-ios`, versions <= v5.9
```
git clone --branch ios-v5.9.0 \
https://github.com/mapbox/mapbox-gl-native-ios.git \
tmp/mapbox-gl-native-ios
cd tmp/mapbox-gl-native-ios
make iproj
```
`mapbox-gl-native-ios`, versions > 6.0, or master
```
git clone \
https://github.com/mapbox/mapbox-gl-native-ios.git \
tmp/mapbox-gl-native-ios
cd tmp/mapbox-gl-native-ios
make iproj
```
2. The call to `make iproj` will automatically open the Xcode Project on your development Mac.
3. Change the Scheme to `CI`, which is already configured in the source for CI. On your development Mac, choose `Product` > `Create Bot`.
4. Add Pre-Integration Triggers
1. `environment` - Git repo metadata & Build versions
1. project specific build commands - for your version of `mapbox-gl-native-ios`
---
### Example Data
* Example Data is generated from a project that makes use of these scripts on GitHub, [roblabs / openmaptiles-ios-demo](https://github.com/roblabs/openmaptiles-ios-demo)
Project & Development Environment `metadata` 🤖
```
Sat Sep 19 13:35:34 PDT 2020
PROJECT_DIR = /Users/roblabs/Documents/github/roblabs/openmaptiles-ios-demo/tmp/openmaptiles-ios-demo
gitBranch = master
gitSHA = aaa53c24cce044e2e2fbfc49b56bd83d825b969d
CURRENT_PROJECT_VERSION = 0
MARKETING_VERSION = 1.341.0
DEVELOPMENT_TEAM = R7O3BWLEA8BS
PREBUILD_LOG = /Users/roblabs/Documents/github/roblabs/openmaptiles-ios-demo/tmp/openmaptiles-ios-demo/prebuild.log
ProductName: Mac OS X
ProductVersion: 10.15.6
BuildVersion: 19G2021
Xcode 11.7
Build version 11E801a
```
---
#### `XCS` Environment Variables
If built using Xcode Server *Bots*, then log several key `XCS_` environment variables. See Apple's [Xcode Server Environment Variable Reference](https://developer.apple.com/library/archive/documentation/IDEs/Conceptual/xcode_guide-continuous_integration/EnvironmentVariableReference.html).
Example Xcode Server Environment Variables 🤖
```
XCS = 1
XCS_BOT_NAME = OSM2VectorTiles Bot
XCS_BOT_ID = drb3o4b067dec6e781b4976604a291
XCS_BOT_TINY_ID = CB1D194
XCS_INTEGRATION_ID = drb3o4b067dec6e781b4976604a291
XCS_INTEGRATION_TINY_ID = R698E33
XCS_INTEGRATION_NUMBER = 4
XCS_INTEGRATION_RESULT = unknown
XCS_SOURCE_DIR = /Users/roblabs/Library/Caches/XCSBuilder/Bots/drb3o4b067dec6e781b4976604a291/Source
XCS_OUTPUT_DIR = /Users/roblabs/Library/Caches/XCSBuilder/Integration-drb3o4b067dec6e781b4976604a291
XCS_DERIVED_DATA_DIR = /Users/roblabs/Library/Caches/XCSBuilder/Bots/drb3o4b067dec6e781b4976604a291/DerivedData
XCS_XCODEBUILD_LOG = /Users/roblabs/Library/Caches/XCSBuilder/Integration-drb3o4b067dec6e781b4976604a291/xcodebuild.log
INTEGRATION_URL = https://roblabs.local/xcode/bots/CB1D194/integrations/R698E33
# Log data generated from this script: ci.sh
PREBUILD_LOG = /Users/roblabs/Library/Caches/XCSBuilder/Bots/drb3o4b067dec146e781b4976604a291/Source/openmaptiles-ios-demo/prebuild.RB1A194.4.log
```
---
#### Xcode Server URLs
You can also log some interesting URL's from the [Xcode Server API Reference](https://developer.apple.com/library/archive/documentation/Xcode/Conceptual/XcodeServerAPIReference/Bots.html)
Example Xcode Server URLs 🤖
```
http://Bots JSON = https://oldSanJuan.local:20343/api/bots
http://bots/latest = https://oldSanJuan.local/xcode/bots/latest
http://latest this bot = https://oldSanJuan.local/xcode/bots/latest/EC6DB3B
http://Integration JSON = https://oldSanJuan.local/xcode/internal/api/integrations/771613596b2cdb2a24eaa2108be1b1
http://Download = https://oldSanJuan.local/xcode/internal/api/integrations/771613596b2cdb2a24eaa2108be1b1/assets
xcbot://See Bot in Xcode = xcbot://oldSanJuan.local/botID/dcb3a48067dec1e781b49766016a8f/integrationID/771613596b2cdb2a24eaa2108be1b1
```
---
### `XCS` and the Build Number
How to add the `XCS` *integration* or build number into your Xcode project.
* XCS builds will automatically update the build number
* Example, If you are doing a non `XCS` build with the following values for current & marketing version then,
* The variable `${XCS_INTEGRATION_NUMBER}` will be `""` or null.
* Local builds version will be `1.278.314` with a build number of `314`
* An example `XCS` build version for the **101** *st* build will be 1.278.314**101** with a build number of 314**101**.
* To acheive this, hand edit all instances in file `.xcodeproj/project.pbxproj`. It is not possible to do this in Xcode directly.
```
CURRENT_PROJECT_VERSION = "314${XCS_INTEGRATION_NUMBER}";
MARKETING_VERSION = "1.278.314${XCS_INTEGRATION_NUMBER}";
```
---
### `ExportOptions.plist`
You can use `XCS` with open source projects and apply your own signing credentials for deploying to devices in your local lab. See the file `ExportOptions.plist`.
* `Configuration` > `Archive` > `Use Custom Export Options Plist`
---
*When you apply a proper `ExportOptions.plist`, then you can*
* `Install on device...`
* `Show in Organizer...`
---
*Viewing `ExportOptions.plist` in Xcode*
#### Documentation
Documentation for the Export Options can be found by typing:
`xcodebuild -h`
Here are some of those settings after running the online documentation for these settings. You can review Apple [Technical Note TN2339](https://developer.apple.com/library/archive/technotes/tn2339/_index.html#//apple_ref/doc/uid/DTS40014588-CH1-WHAT_KEYS_CAN_I_PASS_TO_THE_EXPORTOPTIONSPLIST_FLAG_) for more information.
`destination` : String
> Determines whether the app is exported locally or uploaded to Apple. Options are `export` or `upload`. The available options vary based on the selected distribution method. Defaults to `export`.
`method` : String
> Describes how Xcode should export the archive. Available options: `app-store`, `validation`, `ad-hoc`, `package`, `enterprise`, `development`, `developer-id`, and `mac-application`. The list of options varies based on the type of archive. Defaults to `development`.
`signingStyle` : String
> The signing style to use when re-signing the app for distribution. Options are `manual` or `automatic`. Apps that were automatically signed when archived can be signed manually or automatically during distribution, and default to automatic. Apps that were manually signed when archived must be manually signed during distribution, so the value of signingStyle is ignored.
`stripSwiftSymbols` : Bool
> Should symbols be stripped from Swift libraries in your IPA? Defaults to YES.
`teamID` : String
> The Developer Portal team to use for this export. Defaults to the team used to build the archive.
`uploadBitcode` : Bool
> For App Store exports, should the package include bitcode? Defaults to YES.
`uploadSymbols` : Bool
> For App Store exports, should the package include symbols? Defaults to YES.