John Ferguson Smart Hudson Continuous Integration for the Masses Creative Commons Edition Jenkins The Definitive Guide Copyright .................................................................................................................... xix Foreword ..................................................................................................................... xxi Preface ...................................................................................................................... xxiii 1. Audience ....................................................................................................... xxiii 2. Book Layout .................................................................................................. xxiii 3. Jenkins or Hudson? ......................................................................................... xxiii 4. Font Conventions ............................................................................................ xxiv 5. Command-Line Conventions ............................................................................. xxiv 6. Contributors .................................................................................................... xxv 7. The Review Team ........................................................................................... xxvi 8. Book Sponsors ................................................................................................ xxvi 8.1. Wakaleo Consulting .............................................................................. xxvi 8.2. CloudBees .......................................................................................... xxvii 8.3. Odd-e ................................................................................................ xxvii 9. Using Code Examples .................................................................................... xxviii 10. Safari® Books Online ................................................................................... xxviii 11. How to Contact Us ........................................................................................ xxix 12. Acknowledgments .......................................................................................... xxix 1. Introducing Jenkins ...................................................................................................... 1 1.1. Introduction ..................................................................................................... 1 1.2. Continuous Integration Fundamentals .................................................................... 1 1.3. Introducing Jenkins (née Hudson) ........................................................................ 2 1.4. From Hudson to Jenkins—A Short History ............................................................ 3 1.5. Should I Use Jenkins or Hudson? ......................................................................... 4 1.6. Introducing Continuous Integration into Your Organization ....................................... 5 1.6.1. Phase 1—No Build Server ....................................................................... 5 1.6.2. Phase 2—Nightly Builds .......................................................................... 5 1.6.3. Phase 3—Nightly Builds and Basic Automated Tests ..................................... 5 1.6.4. Phase 4—Enter the Metrics ...................................................................... 6 1.6.5. Phase 5—Getting More Serious About Testing ............................................. 6 1.6.6. Phase 6—Automated Acceptance Tests and More Automated Deployment......... 6 1.6.7. Phase 7—Continuous Deployment ............................................................. 6 1.7. Where to Now? ................................................................................................ 7 2. Your First Steps with Jenkins ........................................................................................ 9 2.1. Introduction ..................................................................................................... 9 2.2. Preparing Your Environment ............................................................................... 9 2.2.1. Installing Java ...................................................................................... 10 2.2.2. Installing Git ........................................................................................ 11 2.2.3. Setting Up a GitHub Account .................................................................. 11 2.2.4. Configuring SSH Keys ........................................................................... 12 2.2.5. Forking the Sample Repository ................................................................ 12 2.3. Starting Up Jenkins .......................................................................................... 14 2.4. Configuring the Tools ...................................................................................... 17 iv 2.4.1. Configuring Your Maven Setup ............................................................... 18 2.4.2. Configuring the JDK ............................................................................. 19 2.4.3. Notification .......................................................................................... 20 2.4.4. Setting Up Git ...................................................................................... 20 2.5. Your First Jenkins Build Job ............................................................................. 21 2.6. Your First Build Job in Action .......................................................................... 26 2.7. More Reporting—Displaying Javadocs ................................................................ 33 2.8. Adding Code Coverage and Other Metrics ........................................................... 35 2.9. Conclusion ..................................................................................................... 41 3. Installing Jenkins ....................................................................................................... 43 3.1. Introduction .................................................................................................... 43 3.2. Downloading and Installing Jenkins .................................................................... 43 3.3. Preparing a Build Server for Jenkins ................................................................... 46 3.4. The Jenkins Home Directory ............................................................................. 47 3.5. Installing Jenkins on Debian or Ubuntu ............................................................... 48 3.6. Installing Jenkins on Redhat, Fedora, or CentOS ................................................... 49 3.7. Installing Jenkins on SUSE or OpenSUSE ........................................................... 50 3.8. Running Jenkins as a Stand-Alone Application ..................................................... 51 3.9. Running Jenkins Behind an Apache Server .......................................................... 54 3.10. Running Jenkins on an Application Server .......................................................... 55 3.11. Memory Considerations .................................................................................. 56 3.12. Installing Jenkins as a Windows Service ............................................................ 56 3.13. What’s in the Jenkins Home Directory ............................................................... 60 3.14. Backing Up Your Jenkins Data ........................................................................ 64 3.15. Upgrading Your Jenkins Installation .................................................................. 64 3.16. Conclusion ................................................................................................... 65 4. Configuring Your Jenkins Server .................................................................................. 67 4.1. Introduction .................................................................................................... 67 4.2. The Configuration Dashboard—The Manage Jenkins Screen .................................... 67 4.3. Configuring the System Environment .................................................................. 70 4.4. Configuring Global Properties ............................................................................ 71 4.5. Configuring Your JDKs .................................................................................... 72 4.6. Configuring Your Build Tools ........................................................................... 74 4.6.1. Maven ................................................................................................. 74 4.6.2. Ant ..................................................................................................... 76 4.6.3. Shell-Scripting Language ........................................................................ 77 4.7. Configuring Your Version Control Tools ............................................................. 77 4.7.1. Configuring Subversion .......................................................................... 77 4.7.2. Configuring CVS .................................................................................. 77 4.8. Configuring the Mail Server .............................................................................. 78 4.9. Configuring a Proxy ........................................................................................ 79 4.10. Conclusion ................................................................................................... 80 5. Setting Up Your Build Jobs ......................................................................................... 81 v 5.1. Introduction .................................................................................................... 81 5.2. Jenkins Build Jobs ........................................................................................... 81 5.3. Creating a Freestyle Build Job ........................................................................... 82 5.3.1. General Options .................................................................................... 82 5.3.2. Advanced Project Options ...................................................................... 84 5.4. Configuring Source Code Management ................................................................ 85 5.4.1. Working with Subversion ....................................................................... 86 5.4.2. Working with Git .................................................................................. 88 5.5. Build Triggers ............................................................................................... 100 5.5.1. Triggering a Build Job Once Another Build Job Has Finished ...................... 101 5.5.2. Scheduled Build Jobs ........................................................................... 101 5.5.3. Polling the SCM ................................................................................. 102 5.5.4. Triggering Builds Remotely .................................................................. 103 5.5.5. Manual Build Jobs ............................................................................... 105 5.6. Build Steps ................................................................................................... 105 5.6.1. Maven Build Steps .............................................................................. 105 5.6.2. Ant Build Steps .................................................................................. 107 5.6.3. Executing a Shell or Windows Batch Command ........................................ 107 5.6.4. Using Jenkins Environment Variables in Your Builds ................................. 109 5.6.5. Running Groovy Scripts ....................................................................... 111 5.6.6. Building Projects in Other Languages ..................................................... 113 5.7. Post-Build Actions ......................................................................................... 113 5.7.1. Reporting on Test Results ..................................................................... 113 5.7.2. Archiving Build Results ....................................................................... 114 5.7.3. Notifications ....................................................................................... 117 5.7.4. Building Other Projects ........................................................................ 118 5.8. Running Your New Build Job .......................................................................... 118 5.9. Working with Maven Build Jobs ...................................................................... 118 5.9.1. Building Whenever a SNAPSHOT Dependency Is Built .............................. 119 5.9.2. Configuring the Maven Build ................................................................ 120 5.9.3. Post-Build Actions ............................................................................... 121 5.9.4. Deploying to an Enterprise Repository Manager ........................................ 122 5.9.5. Deploying to Commercial Enterprise Repository Managers .......................... 125 5.9.6. Managing Modules .............................................................................. 126 5.9.7. Extra Build Steps in Your Maven Build Jobs ............................................ 127 5.10. Using Jenkins with Other Languages ............................................................... 127 5.10.1. Building Projects with Grails ............................................................... 127 5.10.2. Building Projects with Gradle .............................................................. 129 5.10.3. Building Projects with Visual Studio MSBuild ........................................ 132 5.10.4. Building Projects with NAnt ................................................................ 133 5.10.5. Building Projects with Ruby and Ruby on Rails ....................................... 134 5.11. Conclusion .................................................................................................. 136 6. Automated Testing ................................................................................................... 137 vi 6.1. Introduction .................................................................................................. 137 6.2. Automating Your Unit and Integration Tests ....................................................... 138 6.3. Configuring Test Reports in Jenkins .................................................................. 139 6.4. Displaying Test Results .................................................................................. 141 6.5. Ignoring Tests ............................................................................................... 144 6.6. Code Coverage .............................................................................................. 146 6.6.1. Measuring Code Coverage with Cobertura ............................................... 147 6.6.2. Measuring Code Coverage with Clover .................................................... 156 6.7. Automated Acceptance Tests ........................................................................... 157 6.8. Automated Performance Tests with JMeter ......................................................... 160 6.9. Help! My Tests Are Too Slow! ........................................................................ 168 6.9.1. Add More Hardware ............................................................................ 168 6.9.2. Run Fewer Integration/Functional Tests ................................................... 169 6.9.3. Run Your Tests in Parallel .................................................................... 169 6.10. Conclusion .................................................................................................. 170 7. Securing Jenkins ...................................................................................................... 171 7.1. Introduction .................................................................................................. 171 7.2. Activating Security in Jenkins .......................................................................... 171 7.3. Simple Security in Jenkins .............................................................................. 172 7.4. Security Realms—Identifying Jenkins Users ....................................................... 173 7.4.1. Using Jenkins’s Built-in User Database ................................................... 173 7.4.2. Using an LDAP Repository ................................................................... 176 7.4.3. Using Microsoft Active Directory ........................................................... 178 7.4.4. Using Unix Users and Groups ............................................................... 179 7.4.5. Delegating to the Servlet Container ......................................................... 179 7.4.6. Using Atlassian Crowd ......................................................................... 180 7.4.7. Integrating with Other Systems .............................................................. 181 7.5. Authorization—Who Can Do What ................................................................... 183 7.5.1. Matrix-based Security .......................................................................... 183 7.5.2. Project-based Security .......................................................................... 187 7.5.3. Role-based Security ............................................................................. 189 7.6. Auditing—Keeping Track of User Actions ......................................................... 191 7.7. Conclusion ................................................................................................... 194 8. Notification ............................................................................................................. 197 8.1. Introduction .................................................................................................. 197 8.2. Email Notification .......................................................................................... 197 8.3. More Advanced Email Notification ................................................................... 198 8.4. Claiming Builds ............................................................................................ 202 8.5. RSS Feeds .................................................................................................... 203 8.6. Build Radiators ............................................................................................. 204 8.7. Instant Messaging .......................................................................................... 206 8.7.1. IM Notification with Jabber .................................................................. 206 8.7.2. IM Notification using IRC .................................................................... 210 vii 8.8. IRC Notification ............................................................................................ 211 8.9. Desktop Notifiers ........................................................................................... 214 8.10. Notification via Notifo .................................................................................. 217 8.11. Mobile Notification ...................................................................................... 219 8.12. SMS Notification ......................................................................................... 220 8.13. Making Noise .............................................................................................. 222 8.14. Extreme Feedback Devices ............................................................................ 224 8.15. Conclusion .................................................................................................. 226 9. Code Quality ........................................................................................................... 227 9.1. Introduction .................................................................................................. 227 9.2. Code Quality in Your Build Process .................................................................. 228 9.3. Popular Java and Groovy Code Quality Analysis Tools ......................................... 229 9.3.1. Checkstyle ......................................................................................... 229 9.3.2. PMD/CPD .......................................................................................... 232 9.3.3. FindBugs ........................................................................................... 236 9.3.4. CodeNarc ........................................................................................... 238 9.4. Reporting on Code Quality Issues with the Violations Plugin ................................. 239 9.4.1. Working with Freestyle Build Jobs ......................................................... 240 9.4.2. Working with Maven Build Jobs ............................................................ 243 9.5. Using the Checkstyle, PMD, and FindBugs Reports ............................................. 245 9.6. Reporting on Code Complexity ........................................................................ 248 9.7. Reporting on Open Tasks ................................................................................ 249 9.8. Integrating with Sonar .................................................................................... 251 9.9. Conclusion ................................................................................................... 255 10. Advanced Builds .................................................................................................... 257 10.1. Introduction ................................................................................................. 257 10.2. Parameterized Build Jobs ............................................................................... 257 10.2.1. Creating a Parameterized Build Job ....................................................... 257 10.2.2. Adapting Your Builds to Work with Parameterized Build Scripts ................. 259 10.2.3. More Advanced Parameter Types ......................................................... 261 10.2.4. Building from a Subversion Tag ........................................................... 262 10.2.5. Building from a Git Tag ..................................................................... 263 10.2.6. Starting a Parameterized Build Job Remotely .......................................... 264 10.2.7. Parameterized Build Job History ........................................................... 265 10.3. Parameterized Triggers .................................................................................. 265 10.4. Multiconfiguration Build Jobs ........................................................................ 268 10.4.1. Setting Up a Multiconfiguration Build ................................................... 268 10.4.2. Configuring a Slave Axis .................................................................... 269 10.4.3. Configuring a JDK Axis ..................................................................... 270 10.4.4. Custom Axis ..................................................................................... 271 10.4.5. Running a Multiconfiguration Build ...................................................... 271 10.5. Generating Your Maven Build Jobs Automatically ............................................. 274 10.5.1. Configuring a Job .............................................................................. 275 viii 10.5.2. Reusing Job Configuration with Inheritance ............................................ 277 10.5.3. Plugin Support .................................................................................. 278 10.5.4. Freestyle Jobs ................................................................................... 281 10.6. Coordinating Your Builds .............................................................................. 281 10.6.1. Parallel Builds in Jenkins .................................................................... 282 10.6.2. Dependency Graphs ........................................................................... 282 10.6.3. Joins ................................................................................................ 283 10.6.4. Locks and Latches ............................................................................. 284 10.7. Build Pipelines and Promotions ...................................................................... 285 10.7.1. Managing Maven Releases with the M2Release Plugin .............................. 286 10.7.2. Copying Artifacts .............................................................................. 289 10.7.3. Build Promotions ............................................................................... 292 10.7.4. Aggregating Test Results .................................................................... 300 10.7.5. Build Pipelines .................................................................................. 301 10.8. Conclusion .................................................................................................. 304 11. Distributed Builds ................................................................................................... 305 11.1. Introduction ................................................................................................. 305 11.2. The Jenkins Distributed Build Architecture ....................................................... 305 11.3. Master/Slave Strategies in Jenkins ................................................................... 306 11.3.1. The Master Starts the Slave Agent Using SSH ......................................... 306 11.3.2. Starting the Slave Agent Manually Using Java Web Start .......................... 310 11.3.3. Installing a Jenkins Slave as a Windows Service ...................................... 313 11.3.4. Starting the Slave Node in Headless Mode ............................................. 314 11.3.5. Starting a Windows Slave as a Remote Service ........................................ 315 11.4. Associating a Build Job with a Slave or Group of Slaves ..................................... 315 11.5. Node Monitoring .......................................................................................... 317 11.6. Cloud Computing ......................................................................................... 318 11.6.1. Using Amazon EC2 ........................................................................... 318 11.7. Using the CloudBees DEV@cloud Service ....................................................... 322 11.8. Conclusion .................................................................................................. 323 12. Automated Deployment and Continuous Delivery ......................................................... 325 12.1. Introduction ................................................................................................. 325 12.2. Implementing Automated and Continuous Deployment ........................................ 326 12.2.1. The Deployment Script ....................................................................... 326 12.2.2. Database Updates .............................................................................. 326 12.2.3. Smoke Tests ..................................................................................... 329 12.2.4. Rolling Back Changes ........................................................................ 329 12.3. Deploying to an Application Server ................................................................. 330 12.3.1. Deploying a Java Application .............................................................. 330 12.3.2. Deploying Scripting-based Applications Like Ruby and PHP ...................... 339 12.4. Conclusion .................................................................................................. 342 13. Maintaining Jenkins ................................................................................................ 345 13.1. Introduction ................................................................................................. 345 ix 13.2. Monitoring Disk Space .................................................................................. 345 13.2.1. Using the Disk Usage Plugin ............................................................... 346 13.2.2. Disk Usage and the Jenkins Maven Project Type ..................................... 348 13.3. Monitoring the Server Load ........................................................................... 349 13.4. Backing Up Your Configuration ..................................................................... 351 13.4.1. Fundamentals of Jenkins Backups ......................................................... 351 13.4.2. Using the Backup Plugin ..................................................................... 353 13.4.3. More Lightweight Automated Backups .................................................. 354 13.5. Archiving Build Jobs .................................................................................... 355 13.6. Migrating Build Jobs .................................................................................... 356 13.7. Conclusion .................................................................................................. 359 A. Automating Your Unit and Integration Tests ................................................................ 361 A.1. Automating Your Tests with Maven ................................................................. 361 A.2. Automating Your Tests with Ant ..................................................................... 366 Index ......................................................................................................................... 371 List of Figures 2.1. Installing Java ......................................................................................................... 10 2.2. Signing up for a GitHub account ................................................................................ 12 2.3. Forking the sample code repository ............................................................................ 13 2.4. Running Jenkins using Java Web Start from the book’s website ....................................... 14 2.5. Java Web Start will download and run the latest version of Jenkins ................................... 15 2.6. Java Web Start running Jenkins ................................................................................. 15 2.7. The Jenkins start page .............................................................................................. 16 2.8. The Manage Jenkins screen ....................................................................................... 17 2.9. The Configure Jenkins screen .................................................................................... 18 2.10. Configuring a Maven installation .............................................................................. 19 2.11. Configuring a JDK installation ................................................................................. 20 2.12. Managing plugins in Jenkins .................................................................................... 21 2.13. Installing the Git plugin .......................................................................................... 21 2.14. Setting up your first build job in Jenkins .................................................................... 23 2.15. Telling Jenkins where to find the source code ............................................................. 24 2.16. Scheduling the build jobs ........................................................................................ 25 2.17. Adding a build step ................................................................................................ 25 2.18. Configuring JUnit test reports and artifact archiving ..................................................... 26 2.19. Your first build job running ..................................................................................... 27 2.20. The Jenkins dashboard ............................................................................................ 27 2.21. A failed build ....................................................................................................... 30 2.22. The list of all the broken tests .................................................................................. 31 2.23. Details about a failed test ........................................................................................ 31 2.24. Now the build is back to normal .............................................................................. 33 2.25. Adding a new build step and report to generate Javadoc ................................................ 34 2.26. Jenkins will add a Javadoc link to your build results ..................................................... 35 2.27. Jenkins has a large range of plugins available ............................................................. 36 2.28. Adding another Maven goal to generating test coverage metrics ...................................... 37 2.29. Configuring the test coverage metrics in Jenkins .......................................................... 38 2.30. Jenkins displays code coverage metrics on the build home page ...................................... 39 2.31. Jenkins lets you display code coverage metrics for packages and classes ........................... 40 2.32. Jenkins also displays a graph of code coverage over time .............................................. 41 3.1. You can download the Jenkins binaries from the Jenkins website ...................................... 44 3.2. Jenkins setup wizard in Windows ............................................................................... 45 3.3. The Jenkins start page .............................................................................................. 46 3.4. Starting Jenkins using Java Web Start ......................................................................... 57 3.5. Installing Jenkins as a Windows service ...................................................................... 58 3.6. Configuring the Jenkins Windows Service ................................................................... 59 3.7. The Jenkins home directory ....................................................................................... 61 3.8. The Jenkins jobs directory ........................................................................................ 62 xii 3.9. The builds directory ................................................................................................. 63 3.10. Upgrading Jenkins from the web interface .................................................................. 65 4.1. You configure your Jenkins installation in the Manage Jenkins screen ............................... 68 4.2. System configuration in Jenkins ................................................................................. 70 4.3. Configuring environment variables in Jenkins ............................................................... 72 4.4. Using a configured environment variable ..................................................................... 72 4.5. JDK configuration in Jenkins ..................................................................................... 73 4.6. Installing a JDK automatically ................................................................................... 74 4.7. Configuring Maven in Jenkins ................................................................................... 75 4.8. Configuring system-wide MVN_OPTS ........................................................................ 76 4.9. Configuring Ant in Jenkins ....................................................................................... 77 4.10. Configuring an email server in Jenkins ...................................................................... 78 4.11. Configuring an email server in Jenkins to use a Google Apps domain .............................. 79 4.12. Configuring Jenkins to use a proxy ........................................................................... 80 5.1. Jenkins supports four main types of build jobs .............................................................. 82 5.2. Creating a new build job .......................................................................................... 83 5.3. Keeping a build job forever ....................................................................................... 83 5.4. To display the Advanced Options, you need to click on the Advanced button ...................... 84 5.5. The “Block build when upstream project is building” option is useful when a single commit can affect several related projects ..................................................................................... 85 5.6. Jenkins provides built-in support for Subversion ............................................................ 86 5.7. Source code browser showing what code changes caused a build ...................................... 87 5.8. System-wide configuration of the Git plugin ................................................................. 89 5.9. Entering a Git repo URL .......................................................................................... 91 5.10. Advanced configuration of a Git repo URL ................................................................ 91 5.11. Advanced configuration of the Git branches to build .................................................... 92 5.12. Branches and regions ............................................................................................. 93 5.13. Choosing strategy .................................................................................................. 95 5.14. Git executable global setup ...................................................................................... 95 5.15. Repository browser ................................................................................................ 96 5.16. Polling log ............................................................................................................ 96 5.17. Results of Git polling ............................................................................................. 97 5.18. Gerrit Trigger ........................................................................................................ 97 5.19. Git Publisher ......................................................................................................... 98 5.20. Merge results ........................................................................................................ 99 5.21. GitHub repository browser ..................................................................................... 100 5.22. GitHub repository browser ..................................................................................... 100 5.23. There are many ways that you can configure Jenkins to start a build job .......................... 100 5.24. Triggering another build job even if the current one is unstable ..................................... 101 5.25. Triggering a build via a URL using a token .............................................................. 104 5.26. Adding