Team Services | TFS 2017 | TFS 2015 | Previous versions (XAML builds)
Notice: Apple's WWDR certificate expired on Feb 14th and as a result you may experience signing failures if you have not updated the cert and removed the old one. Follow the steps outlined by Apple under What should I do if Xcode doesn’t recognize my distribution certificate? to resolve the problem. Note that this also affects development certs despite the title.
Visual Studio Team Services (formerly Visual Studio Online) and Team Foundation Services (TFS) 2015 can be used for building and testing Cordova apps in a Continuous Integration (CI) environment thanks to a new cross-platform agent that supports OSX. The end result is you can use Visual Studio Team Services or TFS to build projects created using Tools for Apache Cordova or any Cordova compliant CLI like the Ionic, PhoneGap, or TACO CLI.
To streamline CI for Cordova-based projects, we have created a series of build tasks (or steps) that you can use: Cordova Build, Cordova Command, Ionic Command, and PhoneGap Command. These tasks will automatically handle fetching the correct version of the appropriate CLI and even setup the correct version of Node.js for you if not present!
- Installing the VS Team Services Extension for Cordova
- Building Android, Windows, or Windows Phone 8.0 on Windows
- Building iOS on OSX
- Optional: Using Gulp for script compilation and running tests
- In Depth: Custom Build Agent Setup
Installing the Cordova Build task
To setup a Cordova build in Visual Studio Team Services or TFS 2015, you will need to install the Cordova Build task in your collection.
- Visual Studio Team Services / Visual Studio Online: Simply install the Visual Studio Team Services Extension for Cordova.
- TFS 2015 Update 1 and Earlier: TFS 2015 Update 1 and below does not support installing Team Services Extensions. Follow the instructions in the cordova-tasks repository to install.
Project setup and build definitions
We'll assume for the purposes of this tutorial that you want to build a Cordova app for Android, iOS, and Windows and you want to build everything on Windows except iOS. We will accomplish this by using the concept of a "demand" in two separate build definitions to route the work to the correct OS.
Create the definition
Open your team project in your web browser.
- Visual Studio Team Services
Create a build definition.
Click Empty to start with an empty definition.
Building Android, Windows, or Windows Phone 8.0 on Windows
Detailed instructions on creating build definitions in TFS 2015 can be found in its documentation, but here are the specific settings you will need to use to configure a build to run on a Windows agent. We'll start with Android but the steps here generally apply to the Windows and WP8 platforms as well.
First we need to ensure that this particular build runs on Windows rather than OSX. Under the General tab, add a demand that cmd exists.
Next we will add some build steps.
Build: Cordova Build
- Platform: android
- Configuration: debug or release. You can also use a variable from the Variables tab to allow you to select at build time.
- Cordova Version: Version of the Cordova CLI you want to use to build. If you're using Tools for Apache Cordova you can leave this blank and the correct version will be used based on the contents of taco.json. Otherwise, if not specified, it uses the version specified by the CORDOVA_DEFAULT_VERSION environment variable (like in Team Services) and falls back to the latest version if no environment variable is set.
- Android: You may use these values to specify signing information for this build. See securing your signing keys for details.
- Advanced > Working Directory: Location of the Cordova project itself inside your repository.
Utility: Copy and Publish Build Artifacts
- Copy Root: Location specified in Advanced > Output Directory in the Cordova Build step. Defaults to "bin."
- Contents: *
- Artifact Name: bin
- Artifact Type: Server
Finally, save and click "Queue Build..." to test it out!
That's it for Windows! You're now able to build Android. To build Windows or Windows Phone 8.0, follow these same steps and replace the "platform" value with "windows" or "wp8" respectively.
Optional: Multi-Configuration setup for Android, Windows, Windows Phone 8.0
If you intend to build more than just one platform on Windows you can use something called a "Multi-Configuration" setup to build for multiple platforms from a single build definition.
Go to the Variables tab and enter a variable called Platform with a comma separated list of platforms you want to build. Ex: android, windows, wp8
Go to the Options tab, check MultiConfiguration, and set Multipliers to Platform
Update the Platform value for the Cordova Build step to be $(Platform) and update any platform specific options as appropriate.
Next time you build, it will queue up and build all three platforms and store separate artifacts for each using the platform name.
Building iOS on OSX
Now let's create a version of this same build definition to target iOS that will run on a configured cross-platform agent on OSX.
Troubleshooting Tip: You should either setup the cross-platform agent as a launch agent (./svc.sh install agent) or run it as an interactive process (node agent/vsoagent.js) when building an Cordova project targeting iOS due to issues with code signing certificate storage when using a launch daemon.
Right click on the Windows build definition and select "Clone." Once you save you should give this definition a name that indicates it's the iOS build.
Change the Platform value for the Cordova Build step to ios
Update the iOS category for the Cordova Build step. See securing your signing keys for details on the appropriate options to set for your situation. Be sure to check out the "P12 Certificate File" and "Provisioning Profile File" options that can really streamline setup! The Xcode Developer Path option also allows you to specify the path of a different version of Xcode than you have installed locally. (Ex: /Applicaitons/Xcode6.4.app/Contents/Developer will use Xcode 6.4 in MacinCloud.)
Finally, we need to add a demand that will route builds to OSX machines rather than Windows. Under the General tab, remove the "cmd" demand and add a demand that xcode exists.
Troubleshooting Tip: If you encounter a spawn EACCES error when building on a Mac or Linux, be sure all files in the hooks folder to have an "execute bit" set as this a requirement for Cordova. To resolve, add an execute bit to the files in source control or add the following using the Command Line task for each file in the folder: chmod +x <file name goes here>
You are now all set! You can configure either of these build definitions further as you see fit including having them automatically fire off on check-in or adding other validations.
Troubleshooting Tip: See Troubleshooting Tips for Building on OSX in the general Tools for Apache Cordova CI tutorial for tips on resolving common build errors that can occur when building Cordova projects on that operating system.
Optional: Using Gulp for script compilation and running tests
Using Gulp in a CI environment can allow you to easily compile / transpile scripts (TypeScript, LESS, SASS) and even run tests thanks to the "Gulp" and "npm install" build steps.
To add TypeScript compilation into your build definition using Gulp, follow these steps:
Take the sample files (gulpfile.js, package.json, karma.config.js) from the "samples/gulp" folder in this GitHub repo and place them in the root of your project Cordova project
Add these files to source control with your project. From here you can modify gulpfile.js and add other Gulp plugins as you see fit.
Next we will add some Gulp related build steps before the other steps in the definition.
Package: npm (or the older npm install)
If you encounter EPERM errors you may also need to specify the --force option.
Using Gulp to run tests
You can also use the exact same Gulp build step above to run your tests! The scripts from the GitHub repo mentioned above are ready for use with Jasmine, Karma, and PhantomJS. See the Cordova test tutorials for details on setting up Gulp to run your tests.
Next, we will configure the definition to publish your test results to VS Team Services or TFS.
Update the Gulp Task(s) option in the Gulp step above to reference your "test" task. A value of "scripts test" will first compile TypeScript (or anything else you have configured) and then run tests.
Test: Publish Test Results
In Depth: Private build agent setup
As of this writing, you can build Cordova apps targeting Android, Windows, and Windows Phone using the Hosted Agent Pool in Visual Studio Team Services. This allows you to build without setting up a Windows build agent on premise. MacinCloud provides a special plan and streamlined setup experience for Team Services agents targeted at buillding iOS in the cloud. All Cordova prerequisites should already be installed and configured when using the Hosted Agent Pool in Visual Studio Team Services or MacinCloud's special Team Services plan.
If you are not using the Visual Studio Team Services Hosted Agent Pool or MacinCloud's streamlined VS Team Services plan, you can use your own hardware instead. Because of its design, you can easily install the Windows agent on Windows or the cross-platform agent on a Mac and integrate with either TFS or Visual Studio Team Services. The build machine simply needs to have HTTP access to the server with your TFS collection or Visual Studio Team Services.
Custom Agent Setup
Since the build process we will describe here is not directly dependent on MSBuild or Visual Studio for Android, you have two options for installing prerequisites on Windows:
You can install Visual Studio 2015 and select the Tools for Apache Cordova option and let it install the prerequisites for you.
Otherwise you can manually install only the prerequisites needed for the specific platforms you intend to build. For example, you do not need to install Visual Studio at all if you only intend to target Android. See "Installing Dependencies" in the general Tools for Apache Cordova CI tutorial for additional details.
Next you will need to install the Windows build agent to build Android, Windows, or Windows Phone, and the cross-platform build agent on a Mac if you intend to build iOS (and Android if you so desire). See the new build system documentation for information on getting started with setting up an agent. It is important to note that you should setup the cross-platform agent as a launch agent (./svc.sh install agent) or run it as an interactive process (node agent/vsoagent.js) when building an Cordova project targeting iOS due to issues with code signing certificate storage when using a launch daemon.
Troubleshooting Tip: See Internet Access & Proxy Setup" in the general Tools for Apache Cordova CI tutorial if your build servers have limited Internet connectivity or require routing traffic through a proxy.
You should set the following environment variables if they have not already been configured on each server you have configured a build agent.
|Variable||Required For||Purpose||Default Location (Visual Studio 2015)|
|ANDROID_HOME||Android||Location of the Android SDK||C:\Program Files (x86)\Android\android-sdk|
|JAVA_HOME||Android||Location of Java||C:\Program Files (x86)\Java\jdk1.7.0_55|
|ANT_HOME||Android when building using Ant (not Gradle)||Location of Ant||C:\Program Files (x86)\Microsoft Visual Studio 14.0\Apps\apache-ant-1.9.3|
|GRADLE_USER_HOME||Optional||Overrides the default location Gradle build system dependencies should be installed when building Android using Cordova 5.0.0+||If not specified, uses %USERPROFILE%.gradle on Windows or ~/.gradle on OSX or Linux|
|CORDOVA_CACHE||Optional||Overrides the default location used by the Cordova Build Task to cache installs of multiple versions of Cordova.||If not specified, uses %APPDATA%\cordova-cache on Windows and ~/.cordova-cache on OSX or Linux|
Setting your path
The following will also need to be in your path:
Node.js should already be in your path on OSX/Linux simply by the fact that you've setup the cross-platform build agent. However, on Windows you should ensure both Node.js and the global modules folder (aka "prefix" location) is in your path as there a circumstances where one or the other may be missing. The default location of Node.js on Windows is %PROGRAMFILES(x86)%\nodejs while the default location where global node modules are installed is %APPDATA%\npm.
Gulp should also be installed globally if you intend to use the Gulp task. Once Node.js is installed, simply type npm install -g gulp from the command line.
%ANT_HOME%\bin (or $ANT_HOME\bin on OSX/Linux) should be added to your path if you are using a version of Cordova < 5.0.0 or have checked the "Force Ant" build option.
- Learn about the Cordova and Ionic Command tasks
- Learn about securing your signing keys
- Check out the source code
- Learn about Tools for Apache Cordova
- Read tutorials and learn about tips, tricks, and known issues for Cordova
- Download samples from our Cordova Samples repository
- Follow us on Twitter
- Visit our site http://aka.ms/cordova
- Ask for help on StackOverflow
What other kinds of apps can I build?
What other kinds of build steps are available?
How do we protect our codebase from build breaks?
Git: Improve code quality with branch policies with an option to require that code builds before it can be merged to a branch. This option is not available for GitHub repos.
TFVC: Use gated check-in.
How do I modify other parts of my build definition?
Specify your build steps to run tests, scripts, and a wide range of other processes.
Specify build options such as building multiple configurations and creating work items on failure.
Specify the repository to pick the source of the build and modify options such as how the agent workspace is cleaned.
Set build triggers to modify how your CI builds run and to specify scheduled builds.
Specify general build definition settings to specify how completed builds are named and change other options.
Specify build retention policies to automatically delete old builds.
I selected parallel multi-configuration, but only one build is running at a time.
If you're using Team Services, you might need more concurrent pipelines. See Concurrent build and release pipelines in Visual Studio Team Services.
How do I see what has changed in my build definition?
Do I need a build agent?
You need at least one agent to run your build. Get an agent.
I can't select a default agent queue and I can't queue my build. How do I fix this?