Jenkins : RunDeck Plugin

This plugin is a Notifier that will talk to a RunDeck instance (via its HTTP API) to schedule a job execution on RunDeck after a successful build on Jenkins.
It is also a Trigger that will schedule a build on Jenkins after a job execution on RunDeck (using RunDeck WebHook Notification).
In addition, it turns Jenkins into an Option provider for RunDeck, if you want to use your Jenkins build artifacts as an option to a RunDeck job.

Table of Contents

Use

RunDeck is an open-source tool for automating tasks on multiple nodes, with both a CLI and a web-based interface. You can use it to deploy your application to multiple nodes/appserv easily. It has a concept of jobs and build similar to Jenkins.

You have 3 ways to use this plugin :

• build a "deployment pipeline", (the "0-click deployment process") : you commit a change, Jenkins picks it up, build, test and so on, and then triggers a job execution on RunDeck for deploying your application. This requires some configuration on Jenkins (both global configuration and job configuration), to link a Jenkins job with a RunDeck job.
• continue your pipeline after the deployment : RunDeck deploys your application, then triggers a build on Jenkins to run some integration tests (Selenium ?). This requires some configuration on RunDeck (WebHook notification) and on Jenkins (Trigger configuration, and optionally filter the notifications from RunDeck).
• use Jenkins as an Option provider for RunDeck : when you execute a RunDeck job, you can have an (input) option, whose values could be retrieve from an external system (here, Jenkins). So you can have a RunDeck-job that use a Jenkins-artifact (from a Jenkins-build) as an input.

Note that you can combine those use-cases.

Deployment Pipeline

The goal is to have a 0-click deployment process : you commit a change, Jenkins picks it up, build, test and so on, and then triggers a job execution on RunDeck for deploying your application.
You can also have an "on-demand" process : configure a "tag" in the job configuration (see below), and the plugin will only notify RunDeck if the tag is present in the SCM changelog (= in the commit message).

Configuration

First, you need to configure your RunDeck instance on the main Jenkins configuration page :

As of Rundeck plugin version 3.0, you can specify an Authtoken instead of Login/Password.  Additionally you can set the API version if you need to use a lower number than the latest version.

You can use the "Test Connection" button to make sure that Jenkins can talk to your RunDeck instance :

Then, for each Jenkins job, configure the target RunDeck job that should be executed, along with its options :

• Note that the "options" should be expressed in the java-properties format, and that Jenkins environment variables are expanded when making the RunDeck API calls (for more details, read the integrated-help in your Jenkins instance by clicking the "?" icon next to the "options" field).
• The "tag" field is used to perform "on-demand" job scheduling on RunDeck : if the value is not empty, we will check if the SCM changelog (= the commit message) contains the given tag, and only schedule a job execution if it is present. For example you can set the value to "#deploy". Note that if this value is left empty, we will ALWAYS schedule a job execution.
• You can choose to wait for the RunDeck job to finish before finishing the Jenkins build. Otherwise, the default behavior is to trigger a RunDeck job, and finish the Jenkins build (usually before the RunDeck job has ended).
• If the last checkbox is checked, then a failure to schedule the job execution on RunDeck will fail the Jenkins build. Otherwise, the RunDeck integration won't interact with the result of your Jenkins build (even if RunDeck is down).

Post-deployment job

The goal is to continue the deployment pipeline after a successful deployment : RunDeck deploys your application, and triggers a build on Jenkins to run some integration tests (using Selenium for example).

Configuration

First, you need to configure the WebHook Notification in your RunDeck jobs. Set it to the url http://JENKINS_HOST/plugin/rundeck/webhook/.

Then, configure the "RunDeck Trigger" on your Jenkins jobs : activate it, and optionally filter the notifications from RunDeck.

Use

If your Jenkins job is started by a RunDeck notification, you can access the data of the RunDeck notification as environment variables :

• RDECK_JOB_ID : the ID (UUID) of the job
• RDECK_JOB_NAME : the name of the job
• RDECK_JOB_GROUP : the group of the job
• RDECK_JOB_DESCRIPTION : the description of the job
• RDECK_PROJECT : the name of the project
• RDECK_EXEC_ID : the ID of the execution
• RDECK_EXEC_STATUS : the status of the execution (one of SUCCEEDED, FAILED or ABORTED)
• RDECK_EXEC_STARTED_BY : the user who started the execution
• RDECK_EXEC_STARTED_AT : the date at which the execution started
• RDECK_EXEC_ENDED_AT : the date at which the execution ended
• RDECK_EXEC_ABORTED_BY : the user who aborted the execution (if the status is ABORTED)
• RDECK_EXEC_DURATION_MILLIS : the duration of the execution, in milli-seconds
• RDECK_EXEC_DURATION_SECONDS : the duration of the execution, in seconds
• RDECK_EXEC_DURATION : the duration of the execution, as a human-readable string ("3 minutes 34 seconds")
• RDECK_EXEC_SHORT_DURATION : the duration of the execution, as a short human-readable string ("0:03:34.187")
• RDECK_EXEC_URL : the url of the execution (on the RunDeck Web GUI)
• RDECK_EXEC_DESCRIPTION : the description of the execution
• RDECK_EXEC_ARG_[NAME] : the value of a Job option passed to the execution (plugin version 3.0 or later)

Option Provider

Using Jenkins as an Option provider for RunDeck is very easy, because you don't need to configure anything on the Jenkins side. You just need to point your RunDeck option "remote url" to one of the following url :

Option Provider for artifacts

List all artifacts for a given project / build, with a reference to the absolute url of the artifact. Useful if you have multiple artifacts to deploy (one per architecture for example).
Example (RunDeck screen when executing a job with an "artifact" option, taking its values from Jenkins) :

The url : http://JENKINS_HOST/plugin/rundeck/options/artifact

• The parameter project is mandatory (name of the job)
• The parameter build is optional (default value is 'last'). It could be either a build number, or "last", "lastStable" or "lastSuccessful".
• The parameter artifactRegex is optional. It is a java-regex used to filter the artifacts to return (if empty, all artifacts will be returned).

Example : http://JENKINS_HOST/plugin/rundeck/options/artifact?project=my-job&build=lastSuccessful&artifactRegex=.*\.war

Option Provider for builds

List all builds (versions) for a given project / artifact, with a reference to the absolute url of the artifact. Useful if you have only 1 main artifact, but want to easily re-deploy an older version of the artifact.
Example (RunDeck screen when executing a job with a "build" option, taking its values from Jenkins) :

The url : http://JENKINS_HOST/plugin/rundeck/options/build

• The parameter project is mandatory (name of the job)
• Either the parameter artifact (exact filename of the artifact) or artifactRegex (java-regex matching the filename of the artifact) is mandatory
• The parameter limit is optional. It should be an integer, and is used to limit the number of builds (versions) to return.
• The parameters includeLastStableBuild, includeLastSuccessfulBuild and includeLastBuild are optional booleans. If it is equals to "true", then we will add an entry for the last / last stable / last successful build.

Example : http://JENKINS_HOST/plugin/rundeck/options/build?project=my-job&artifact=my-webapp.war&limit=5&includeLastSuccessfulBuild=true&includeLastStableBuild=true

Option Provider Access

Note: Rundeck will call the url anonymously which means the Jenkins job should provide access to Discover and Read the job. See Matrix based security documentation: https://wiki.jenkins-ci.org/display/JENKINS/Matrix-based+security#Matrix-basedsecurity-Job

Compatibility Matrix

This plugin is not compatible with all versions of RunDeck

If you are using Plugin version 3.x and need to access an older Rundeck server, you can set the API version in the plugin settings.

You can find older versions of the plugin here : http://maven.jenkins-ci.org/content/repositories/releases/org/jenkins-ci/plugins/rundeck/

FAQ

Known Issues

• If you have invalid links to RunDeck executions, check your RunDeck configuration : fix the property "grails.serverURL" in the file $RDECK_HOME/server/config/rundeck-config.properties.
• With the versions 1.x of the plugin, you can't have RunDeck jobs with the same groupPath/jobName on multiple projects.
• Remote options getting 400 server error from Jenkins probably mean you need to grant anonymous access to Discover and Read the Jenkins project

Links

• Sources on github : https://github.com/jenkinsci/rundeck-plugin
• Download binaries (.hpi files) on nexus : http://maven.jenkins-ci.org/content/repositories/releases/org/jenkins-ci/plugins/rundeck/

Change Log

Version 3.6.1 (Jan 26, 2017)

• JENKINS-34510 Improve Jenkins startup time and Rundeck jobs generation with job-dsl thanks to caching (please note: it has to be enabled explicitly in the global config)
• JENKINS-31423 Allow build parameters or references to environment variables in 'Job Identifier' field
• Add Jenkins Pipelines support to Option Provider
• Update RunDeck API Java client library to 13.1

TODO list

• Internationalization
• Option provider : add integration with the Promoted Builds Plugin and/or Promoted Builds Simple Plugin so that we can filter only "promoted" builds.
• Use a drop-down field to select the RunDeck job (list of jobs retrieved using the API) instead of the basic text field

Previous versions

Version 3.6.0 - skipped

Version 3.5.4 (May 19, 2016)

• New: JENKINS-22851 Support multiple Rundeck installations: Configure multiple Rundeck instances (in the global config), and choose the instance to use in the job configuration
• New: JENKINS-31150 Support Multiple SCM tags for rundeck notifier
• Fixed: JENKINS-28697 Aborted job is marked as SUCCESS if "Wait for Rundeck" is used

Version 3.5 (Oct 20, 2015)

• Use display name for the build name
• Set the build result to failure when rundeck fails AND shouldFailTheBuild is set to true. Previously only "marked" the failure; by changing the status of the build to FAIL, other plugins that might be called after rundeck will then be able to detect the status, and handle accordingly.
• Fixed bug where log tailer returned completed even though the job was still running (output was completed). Now both execCompleted and completed are validated
• Filtered out RundeckOutputEntries with empty messages
• No longer depend on last mod for sleep timing since behaviour seems to be not aligned with expectations. Now checking if offset has changed.
• Fixed bug where checkbox wasn't visible in Jenkins
• [JENKINS-28059] Validate API version in test connection

Version 3.4 (Apr 16, 2015)

• Added support to include Rundeck logs in the Jenkins build log
• Support jobs inside folders
• Fix for Exception when using $ARTIFACT_NAME
• Fixed: Badge icons fail is jenkins is not root as "/"
• Changed "RunDeck" text items to the correct "Rundeck"
• Updated the Rundeck client to v12.0 [Fixes JENKINS-27971 — NPE with Rundeck v2.4.2]

Version 3.2 (April 15, 2014)

• Fixed issue with parsing Job options when option values have hyphens

Version 3.1 (March 29, 2014)

• Build the URL using the getRootUrl method, which will use the user configured root url

Version 3.0 (January 28, 2014)

• Update rundeck API client lib to latest (9.3)
• Support Token authentication
• Fix authentication against Rundeck running as a war in Tomcat
• Support RDECK_EXEC_ARG_[NAME] in triggers from Rundeck webhook notifications
• Update naming ("RunDeck" changed to "Rundeck"), update icon

Version 2.11 (January 4, 2012)

• Fix JENKINS-12228 : allow to filter artifacts returned by the option provider, based on a java-regex

Version 2.10 (October 12, 2011)

• Fix icon path URL - Thanks to Joe Passavanti for the patch !
• Small UI fix : don't display job's ID (in rundeck 1.3+, ID is an UUID, and it breaks the UI because it is too long)

Version 2.9 (September 18, 2011)

• Allow to filter nodes when triggering a rundeck job (using the "nodeFilters" parameter)

Version 2.8 (September 16, 2011)

• Configure RunDeck jobs with either a job ID, or an UUID (rundeck 1.3+), or a "reference". A job reference is expressed in the format "project:group/job", for example : "my-project-name:main-group/sub-group/my-job-name", or "my-project-name:my-job-name" (for a job without a group).

Version 2.7 (September 14, 2011)

• Add a build trigger, using RunDeck 1.3 WebHook Notification, so that you can run integration tests with Jenkins after a RunDeck deployment (alternative to the "Wait for RunDeck job to finish ?" checkbox in the notifier configuration and a post-build action to schedule another job)
• Upgrade RunDeck API Java client to version 1.2

Version 2.6 (September 2, 2011)

• Add token expansion for $ARTIFACT_NAME{regex} in options (see http://groups.google.com/group/rundeck-discuss/browse_thread/thread/94a6833b84fdc10b)

Version 2.5 (July 11, 2011)

• Internal refactoring : use the RunDeck API Java client
• Never display the RunDeck password in logs (even in case of error)

Version 2.4 (June 28, 2011)

• Change Job ID support to use Strings instead of Long, allowing UUIDs (coming in RunDeck 1.3) - Thanks to Greg Schueler for the patch !

Version 2.3.1 (June 22, 2011)

• Fix a bug introduced in version 2.3 : NPE related to the new field (shouldWaitForRundeckJob) in already configured jobs. Workaround is to re-save job configuration or use version 2.3.1

Version 2.3 (June 21, 2011)

• Add an option to wait for the RunDeck job to finish (by polling the execution every 5 seconds via the RunDeck API)
• Add a validation button on the job configuration screen, to check the RunDeck job (display job name, group and project)

Version 2.2 (June 17, 2011)

• Add SSL support for RunDeck REST API (trust all certificates and hosts)

Version 2.1 (June 8, 2011)

• New feature : display information about the RunDeck job on the page of a Jenkins job (with a direct link to the RunDeck job details webpage)

Version 2.0.1 (June 8, 2011)

• Rerelease 2.0 and mark it as incompatible with versions 1.x (jobs configuration needs to be updated), so that users can see it in the update-center before updating.

Version 2.0 (June 6, 2011)

• Use the new RunDeck 1.2+ HTTP REST API, and thus is incompatible with RunDeck 1.0 or RunDeck 1.1
• Use "jobId" to reference RunDeck jobs, instead of the "groupPath/jobName" couple, so you'll need to reconfigure your Jenkins jobs. We switched to the "jobId" reference because it is unique across all projects in a RunDeck instance, which is not the case for the "groupPath/jobName" couple.
• Set required Jenkins version to 1.400

Version 1.8 (June 5, 2011)

• Fix JENKINS-9876 : password field in system configuration should be hidden.

Version 1.7 (June 1, 2011)

• New improvement to the option provider : you can now match artifacts with a java-regex in addition to exact-match of the artifact filename (see the new 'artifactRegex' parameter).

Version 1.6 (April 6, 2011)

• Fix a bug with RunDeck 1.2 : scheduling a job with options did not work on RunDeck 1.2.
• Set required Jenkins version to 1.399 (See the thread on the jenkinsci-dev mailing-list).

Version 1.5.1 (March 24, 2011)

• Rerelease 1.5 to properly set required Jenkins version (See the thread on the jenkinsci-dev mailing-list) : the plugin now depends on Jenkins 1.398 (or higher).

Version 1.5 (March 4, 2011)

• Fix bug : when using a "tag" to auto-deploy, we should also check the SCM changelog from upstream builds. So that you can commit to an upstream job, and have all downstream jobs redeployed.

Version 1.4 (March 1, 2011)

• New improvement to the option provider : in addition to the list of artifacts for a given build, you can now get the list of builds (versions) for a given artifact.

Version 1.3 (February 27, 2011)

• Jenkins can now be used as an "Option provider" for RunDeck, if you want to use your Jenkins build artifacts as an option to a RunDeck job.

Version 1.2 (February 27, 2011)

• Jenkins environment variables specified in the "options" are now correctly expanded (GitHub issue)

Version 1.1 (February 11, 2011)

• Do nothing if the build is failing
• Add a link to the RunDeck job execution page (on each Jenkins successful build)
• Validation on the form fields (test if RunDeck is alive, test credentials, etc)

Version 1.0 (February 10, 2011)

• Initial release
• Compatible (and tested) with Jenkins 1.396 and RunDeck 1.1