grunt-jenkins

Manage Jenkins with Grunt

grunt-jenkins

Manage Jenkins with Grunt

Install this grunt plugin next to your project's Gruntfile.js with:

$ npm install grunt-jenkins --save-dev
module.exports = function(grunt) {
  grunt.initConfig({
    // ... 
    jenkins: {
      serverAddress: 'http://localhost:8080',
      pipelineDirectory: 'jenkins-pipeline'   // optional, default: 'pipeline' 
    }
  });
  grunt.loadNpmTasks('grunt-jenkins');
  // ... 
};

Jenkins is authenticated and credentials are in .netrc (preferred)

module.exports = function(grunt) {
  grunt.initConfig({
    // ... 
    jenkins: {
      serverAddress: 'http://localhost:8080',
      netrcMachine: 'ci',
      netrcLocation: '/tmp/.netrc'            // optional, default: '~/.netrc' 
    }
  });
  grunt.loadNpmTasks('grunt-jenkins');
  // ... 
};
module.exports = function(grunt) {
  grunt.initConfig({
    // ... 
    jenkins: {
      serverAddress: 'http://localhost:8080',
      username: 'alf',                        // if only one of username and password 
      password: 's3cret'                      // are provided, no authentication attempted 
    }
  });
  grunt.loadNpmTasks('grunt-jenkins');
  // ... 
};

If a netrcMachine and username/password are provided, the netrc machine will be used. If using username/password, please pass them in via a command line argument instead of hardcoding in the build file.

If you are using Github OAuth for authentication, use API token instead of password which you can find at /user//configure.

grunt-jenkins makes it easier to evolve your Jenkins installation. Jenkins configurations are often created by many people over a long time. Making changes to Jenkins confidently without the appropriate tools can be difficult.

Having configuration in source control gives us the confidence to make changes and know that we can go back to a working state. To create a backup of all jobs run grunt jenkins-backup-jobs. Behind the scenes, grunt-jenkins will:

  1. Create pipelineDirectory if necessary
  2. For each job: Create pipelineDirectory/jobName/config.xml

Having our jobs in source control is great, but it can't make us completely confident. Jenkins encourages users to change the configuration through the UI, and that can leave our backed up version out of sync with the server. grunt-jenkins makes it easy to verify the configuration in source control matches exactly the version running on the server. Create a job as part of your pipeline that runs grunt jenkins-verify-jobs to ensure the configuration is the same as source control.

  • feature: handle periods in job names #11. Thanks @dtJuiceMobile!
  • badges: npm version badge added
  • badges: now built by travisci against node 0.10, 0.12, 4.0, and 4.1
  • docs: readme update for using with github oauth #10. Thanks @floydpraveen!
  • feature: support Jenkins running on NAT network in private cloud #9. Thanks @StefanScherer!
  • bugfix: authentication broken when no auth used #6
  • badges: now built by travisci against node 0.8 and 0.10
  • badges: dependencies are watched by david
  • badges: codeclimate reports on complexity
  • logging: log error when authentication fails #7
  • logging: logs if and where authentication is coming from
  • logging: much more information on requests and responses with --verbose
  • compatibility with password-protected jenkins instances via .netrc or username/password. Thanks @panozzaj!
  • compatibility with grunt 0.4.x
  • inject grunt instance into JenkinsServer and FileSystem classes, as globally-installed grunt instances couldn't be required
  • list all jobs on a server with jenkins-list-jobs
  • backup every job's config.xml to pipelineDirectory/jobName/config.xml with jenkins-backup-jobs
  • verify each configuration in pipelineDirectory/ matches the job configurations on the server with jenkins-verify-jobs
  • install jobs from pipelineDirectory/ with jenkins-install-jobs
  • list all enabled plugins and their versions with jenkins-list-plugins
  • backup plugins to pipelineDirectory/plugins.json with jenkins-backup-plugins
  • verify plugins in pipelineDirectory/plugins.json match the plugins on the server with jenkins-verify-plugins
  • install plugins from pipelineDirectory/plugins.json with jenkins-install-plugins
  • for each of the tasks above, a shorter version exists that will run both: jenkins-list will run jenkins-list-jobs and jenkins-list-plugins

Copyright (c) 2012-2016 sghill Licensed under the MIT license.