Jenkins: The Definitive Guide

John Ferguson Smart

O'REILLY8

• • • Beijing • Cambridge • Farnham Koln Sebastopol Tokyo Table of Contents

Foreword xiii

Preface xv

1. Introducing 1 Introduction 1 Continuous Integration Fundamentals 1 Introducing Jenkins (nee Hudson) 3 From Hudson to Jenkins—A Short History 4 Should I Use Jenkins or Hudson? 5 Introducing Continuous Integration into Your Organization 6 Phase 1—No Build Server 6 Phase 2—Nightly Builds 6 Phase 3—Nightly Builds and Basic Automated Tests 6 Phase 4—Enter the Metrics 7 Phase 5—Getting More Serious About Testing 7 Phase 6—Automated Acceptance Tests and More Automated Deployment 7 Phase 7—Continuous Deployment 7 Where to Now? 8

2. Your First Steps with Jenkins 9 Introduction 9 Preparing Your Environment 9 Installing Java 10 Installing 10 Setting Up a GitHub Account 11 Configuring SSH Keys 11 Forking the Sample Repository 12 Starting Up Jenkins 13 Configuring the Tools 17

v Configuring Your Maven Setup 18 Configuring the JDK 19 Notification 20 Setting Up Git 20 Your First Jenkins Build Job 21 Your First Build Job in Action 26 More Reporting—Displaying Javadocs 33 Adding Code Coverage and Other Metrics 34 Conclusion 40

3. Installing Jenkins 41 Introduction 41 Downloading and Installing Jenkins 41 Preparing a Build Server for Jenkins 44 The Jenkins Home Directory 46 Installing Jenkins on Debian or Ubuntu 47 Installing Jenkins on Redhat, Fedora, or CentOS 48 Installing Jenkins on SUSE or OpenSUSE 48 Running Jenkins as a Stand-Alone Application 49 Running Jenkins Behind an Apache Server 52 Running Jenkins on an Application Server 53 Memory Considerations 54 Installing Jenkins as a Windows Service 54 What's in the Jenkins Home Directory 58 Backing Up Your Jenkins Data 62 Upgrading Your Jenkins Installation 62 Conclusion 63

4. Configuring Your Jenkins Server 65 Introduction 65 The Configuration Dashboard—The Manage Jenkins Screen 65 Configuring the System Environment 68 Configuring Global Properties 69 Configuring Your JDKs 70 Configuring Your Build Tools 72 Maven 73 Ant 74 Shell-Scripting Language 75 Configuring Your Tools 75 Configuring Subversion 76 Configuring CVS 76 Configuring the Mail Server 76 Configuring a Proxy 77

vi | Table of Contents Conclusion 78

5. Setting Up Your Build Jobs 79 Introduction 79 Jenkins Build Jobs 79 80 Creating a Freestyle Build Job General Options 81 Advanced Project Options 82 Configuring Source Code Management 84 Working with Subversion 84 Working with Git 87 Build Triggers 97 98 Triggering a Build Job Once Another Build Job Has Finished Scheduled Build Jobs 98 Polling the SCM 99 Triggering Builds Remotely 100 Manual Build Jobs 102 Build Steps 102 Maven Build Steps 102 Ant Build Steps 104 105 Executing a Shell or Windows Batch Command Using Jenkins Environment Variables in Your Builds 106 Running Groovy Scripts 108 Building Projects in Other Languages 11o Post-Build Actions 11 110 Reporting on Test Results Archiving Build Results 111 Notifications 114 Building Other Projects 115 Running Your New Build Job 115 Working with Maven Build Jobs 115 116 Building Whenever a SNAPSHOT Dependency Is Built Configuring the Maven Build 117 Post-Build Actions 119 119 Deploying to an Enterprise Repository Manager 123 Deploying to Commercial Enterprise Repository Managers Managing Modules 123 Extra Build Steps in Your Maven Build Jobs 123 Using Jenkins with O ther Languages 125 Building Projects with Grails 125 Building Projects with Gradle 127 Building Projects with Visual Studio MSBuild 130 Building Projects with NAnt 131

Table of Contents | vii Building Projects with Ruby and Ruby on Rails 131 Conclusion 133

6. Automated Testing 135 Introduction 135 Automating Your Unit and Integration Tests 136 Configuring Test Reports in Jenkins 137 Displaying Test Results 139 Ignoring Tests 142 Code Coverage 144 Measuring Code Coverage with Cobertura 145 Measuring Code Coverage with Clover 153 Automated Acceptance Tests 155 Automated Performance Tests with JMeter 158 Help! My Tests Are Too Slow! 166 Add More Hardware 167 Run Fewer Integration/Functional Tests 167 Run Your Tests in Parallel 168 Conclusion 168

7. Securing Jenkins 169

Introduction 169 Activating Security in Jenkins 169 Simple Security in Jenkins 170 Security Realms—Identifying Jenkins Users 171 Using Jenkins's Built-in User Database 171 Using an LDAP Repository 175 Using Microsoft Active Directory 176 Using Unix Users and Groups 177 Delegating to the Servlet Container 177 Using Atlassian Crowd 178 Integrating with Other Systems 178 Authorization—Who Can Do What 181 Matrix-based Security 181 Project-based Security 185 Role-based Security 188

Auditing—Keeping Track of User Actions 189 Conclusion 193

8. Notification 195 Introduction 195 Email Notification 195 More Advanced Email Notification 197

viii | Table of Contents Claiming Builds 200 RSS Feeds 201 Build Radiators 202 Instant Messaging 203 1M Notification with Jabber 204 IM Notification using IRC 208 IRC Notification 209 Desktop Notifiers 212 Notification via Notifo 213 Mobile Notification 216 SMS Notification 216 Making Noise 218 Extreme Feedback Devices 221 Conclusion 223

9. Code Quality 225 Introduction 225 Code Quality in Your Build Process 226 Popular Java and Groovy Code Quality Analysis Tools 227 Checkstyle 227 PMD/CPD 230 FindBugs 234 CodeNarc 236 Reporting on Code Quality Issues with the Violations Plugin 237 Working with Freestyle Build Jobs 238 Working with Maven Build Jobs 241 Using the Checkstyle, PMD, and FindBugs Reports 242 245 Reporting on Code Complexity Reporting on Open Tasks 247 Integrating with Sonar 248 Conclusion 252

10. Advanced Builds 253 Introduction 253 Parameterized Build Jobs 253 254 Creating a Parameterized Build Job Adapting Your Builds to Work with Parameterized Build Scripts 254 More Advanced Parameter Types 257 Building from a Subversion Tag 259 260 Building from a Git Tag Starting a Parameterized Build Job Remotely 260 Parameterized Build Job History 261 Parameterized Triggers 262

Table of Contents | ix Multiconfiguration Build Jobs 263 Setting Up a Multiconfiguration Build 264 Configuring a Slave Axis 265 Configuring a JDK Axis 266 Custom Axis 267 Running a Multiconfiguration Build 267 Generating Your Maven Build Jobs Automatically 270 Configuring a Job 271 Reusing Job Configuration with Inheritance 272 Plugin Support 274 Freestyle Jobs 277 Coordinating Your Builds 277 Parallel Builds in Jenkins 277 Dependency Graphs 278 Joins 278 Locks and Latches 280 Build Pipelines and Promotions 281 Managing Maven Releases with the M2Release Plugin 282 Copying Artifacts 285 Build Promotions 288 Aggregating Test Results 295 Build Pipelines 296 Conclusion 299

11. Distributed Builds 301 Introduction 301 The Jenkins Distributed Build Architecture 301 Master/Slave Strategies in Jenkins 302 The Master Starts the Slave Agent Using SSH 303 Starting the Slave Agent Manually Using Java Web Start 307 Installing a Jenkins Slave as a Windows Service 310 the Slave Starting Node in Headless Mode 311 Starting a Windows Slave as a Remote Service 311 Associating a Build Job with a Slave or Group of Slaves 312 Node Monitoring 314 Cloud Computing 314 Using Amazon EC2 315 the CloudBees Using DEV@cloud Service 319 Conclusion 321

12. Automated Deployment and Continuous Delivery 323 Introduction 323 Implementing Automated and Continuous Deployment 324

x | Table of Contents The Deployment Script 324 Database Updates 325 Smoke Tests 327 Rolling Back Changes 328 Deploying to an Application Server 328 329 Deploying a Java Application Deploying Scripting-based Applications Like Ruby and PHP 339 Conclusion 341

13. Maintaining Jenkins 343 Introduction 343 Monitoring Disk Space 343 Using the Disk Usage Plugin 345 Disk Usage and the Jenkins Maven Project Type 346 Monitoring the Server Load 347 Backing Up Your Configuration 348 Fundamentals of Jenkins Backups 349 Using the Backup Plugin 351 More Lightweight Automated Backups 352 Archiving Build Jobs 353 Migrating Build Jobs 354 Conclusion 358

Appendix: Automating Your Unit and Integration Tests 359

Index 369

Table of Contents | xi