View Source

{jenkins-plugin-info:pluginId=rundeck|sourceDir=rundeck-plugin}
{excerpt}
This plugin is a Notifier that will talk to a [RunDeck|http://www.rundeck.org] 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|http://rundeck.org/docs/RunDeck-Guide.html#option-model-provider] for RunDeck, if you want to use your Jenkins build artifacts as an option to a RunDeck job.
{excerpt}

!logo-rundeck.png!

*Table of Contents*
{toc:style=disc|indent=20px|maxLevel=4|exclude=Plugin Information}

h2. Use

[RunDeck|http://www.rundeck.org] 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*|http://rundeck.org/docs/RunDeck-Guide.html#option-model-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.

h3. 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).

h4. Configuration

First, you need to configure your RunDeck instance on the main Jenkins configuration page :
!jenkins-config.png!

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 :

| !jenkins-config-validation-nok.png! | !jenkins-config-validation-ok.png! |
| _Error message in case of error_ | _Success message when your credentials are valid_ |

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

| !job-config.png! | !job-config-check.png! |
| _The per-job configuration screen_ | _If you click_ "Check Job" _it will display the job details (group, job name and project)_ |

* 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).

h3. 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).

h4. Configuration

First, you need to configure the [WebHook Notification|http://rundeck.org/docs/RunDeck-Guide.html#webhooks] 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.

h4. 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)_

h3. Option Provider

Using Jenkins as an [Option provider|http://rundeck.org/docs/RunDeck-Guide.html#option-model-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 :

h4. 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) :
!option-provider-artifact.png!

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]

h4. 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) :
!option-provider-build.png!

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]

h2. Compatibility Matrix

This plugin is not compatible with all versions of RunDeck

|| Plugin version || RunDeck 1.0 / 1.1 || RunDeck 1.2\+ ||
| 1.x | (/) | (?) |
| 2.x | (x) | (/) |
| 3.x | (x)\\ | (/)\\ |

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/]

h2. FAQ

h4. 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.

h2. 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/]

h2. Change Log

h4. TODO list

* Internationalization
* Configure multiple RunDeck instances (in the global config), and choose the instance to use in the job configuration
* 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

h4. Previous versions


h5. 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

h5. Version 2.11 (January 4, 2012)

* Fix [JENKINS-12228|https://issues.jenkins-ci.org/browse/JENKINS-12228] : allow to filter artifacts returned by the option provider, based on a java-regex

h5. Version 2.10 (October 12, 2011)

* Fix icon path URL - Thanks to [Joe Passavanti|https://github.com/joepcds] for the [patch|https://github.com/vbehar/jenkins-rundeck-plugin/pull/2] \!
* 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)

h5. Version 2.9 (September 18, 2011)

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

h5. 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).

h5. Version 2.7 (September 14, 2011)

* Add a build trigger, using RunDeck 1.3 [WebHook Notification|http://rundeck.org/docs/RunDeck-Guide.html#webhooks], 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|http://vbehar.github.com/rundeck-api-java-client/] to version 1.2

h5. 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])

h5. Version 2.5 (July 11, 2011)

* Internal refactoring : use the [RunDeck API Java client|http://vbehar.github.com/rundeck-api-java-client/]
* Never display the RunDeck password in logs (even in case of error)

h5. 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|https://github.com/gschueler] for the [patch|https://github.com/jenkinsci/rundeck-plugin/pull/1] \!

h5. 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

h5. 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)

h5. Version 2.2 (June 17, 2011)

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

h5. 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)

h5. 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.

h5. Version 2.0 (June 6, 2011)

{note:title=Compatibility Warning !}
This version won't work with RunDeck 1.0/1.1, and the configuration per job has changed, you will need to update the configuration for all your jobs that use this plugin \!
{note}

* Use the new [RunDeck 1.2\+ HTTP REST API|http://rundeck.org/docs/RunDeck-Guide.html#rundeck-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

h5. Version 1.8 (June 5, 2011)

* Fix [JENKINS-9876|https://issues.jenkins-ci.org/browse/JENKINS-9876] : password field in system configuration should be hidden.

h5. 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).

h5. 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|http://groups.google.com/group/jenkinsci-dev/msg/26408e6401dd6ee0]).

h5. 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|http://groups.google.com/group/jenkinsci-dev/msg/26408e6401dd6ee0]) : the plugin now depends on Jenkins 1.398 (or higher).

h5. 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.

h5. 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.

h5. Version 1.3 (February 27, 2011)

* Jenkins can now be used as an "[Option provider|http://rundeck.org/docs/RunDeck-Guide.html#option-model-provider]" for RunDeck, if you want to use your Jenkins build artifacts as an option to a RunDeck job.

h5. Version 1.2 (February 27, 2011)

* Jenkins environment variables specified in the "options" are now correctly expanded ([GitHub issue|https://github.com/vbehar/jenkins-rundeck-plugin/issues/1])

h5. 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)

h5. Version 1.0 (February 10, 2011)

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