Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cynipe/jenkins-capistrano

The capistrano tasks for Jenkins CI Server
https://github.com/cynipe/jenkins-capistrano

capistrano-plugin capistrano-tasks jenkins

Last synced: 2 months ago
JSON representation

The capistrano tasks for Jenkins CI Server

Awesome Lists containing this project

README 

        
# jenkins-capistrano



**Note**: 0.1.0 has incompatible change for Node creation.

see [Release Notes](#release-notes) and [Node Configuration](#node-configuration) for detail.



#### Table of Contents



1. [Overview](#overview)

1. [Installation](#installation)

1. [Usage](#usage)

  * [Job Configuration](#job-configuration)

    * [Disabling Jobs](#disabling-jobs)

  * [Node Configuration](#node-configuraton)

    * [Note for the Credentials Plugin and multistage-extension]()

  * [View Configuration](#view-configuraton)

1. [Don't know how to write config.xml?](#dont-know-how-to-write-configxml)

1. [Known Issues](#known-issues)

  * [Using mutlibyte characters in config.xml](#using-multibyte-characters-in-configxml)

1. [Todo](#todo)

1. [Release Notes](#release-notes)

1. [Contributing](#contributing)



## Overview



The capistrano tasks for Jenkins CI Server which manages following things:



* Job

* Node

* View



## Installation



Add this line to your application's Gemfile::



```

gem 'jenkins-capistrano'

```



And then execute::



```

$ bundle

```



Or install it yourself as::



```

$ gem install jenkins-capistrano

```



## Usage



See example directory or following instructions.



### Job Configuration



The following code will creates or updates Jenkins jobs before each deploy task:



config directory structure(name your config.xml as a job name):

```

config

├── deploy.rb

└── jenkins

     └── jobs

         ├── job-name1.xml

         ├── job-name2.xml

         └── job-name3.xml

```



deploy.rb:

```ruby

set :application, "your-awesome-app"

set :scm, :git

set :repository,  "https://github.com/your/repository.git"



set :jenkins_host, 'http://localhost:8080'

#set :jenkins_username, '' # default empty

#set :jenkins_password, '' # default empty

#set :jenkins_job_config_dir, 'config/jenkins/jobs'



before 'deploy', 'jenkins:deploy_jobs'

```



#### Disabling Jobs



Since 0.0.5, you can disabling jobs using `disabled_jobs` option.

Use this option with [multistage-extension]().



Put the following line into `config/deploy/.rb`:

```

set :disabled_jobs, %w(job1 job2)

```



### Node Configuration



config directory structure(name your json file as a node name):

```

config

├── deploy.rb

└── jenkins

     └── nodes

         ├── node1.xml

         ├── node2.xml

         └── node3.xml

```



sample node configuration:

```xml



  example

  

  /home/jenkins

  5

  EXCLUSIVE

  

  

    dev-slave01.local

    22

    CREDENTIAL-ID-FOR-SLAVE

    -Dfile.encoding=UTF-8

  

  hello

  

    

      

        

        

          

            

          

          2

          LANG

          ja_JP.UTF-8

          ENVIRONMENT

          develop

        

      

    

  



```



deploy.rb:

```ruby

set :application, "your-awesome-app"

set :scm, :git

set :repository,  "https://github.com/your/repository.git"



set :jenkins_host, 'http://localhost:8080'

# set :jenkins_username, '' # default empty

# set :jenkins_password, '' # default empty

# set :jenkins_node_config_dir, 'config/jenkins/nodes'



before 'deploy', 'jenkins:config_nodes'

```



#### Note for the Credentials Plugin and multistage-extension



Recently, Jenkins has changed the slave's auth method to use

[Credentials Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Credentials+Plugin),

and we need to use its id(credentialsId) to create slave configuration.

However, Credentials Plugin doesn't have a REST interface to manage their credentials,

and credentialsId is different on every Jenkins master.



So, if you want to use same config.xml against different masters,

use the ERB template support to specify correct credentialsId like as following:



config/jenkins/nodes/node1.xml.erb:

```xml



  batch-slave

  

  /home/jenkins

  5

  EXCLUSIVE

  

  

    batch-slave

    22

    <%= @credential_id %>

    -Dfile.encoding=UTF-8

  

  hello

  



```



config/deploy.rb

```ruby

set :application, "your-awesome-app"

set :scm, :git

set :repository,  "https://github.com/your/repository.git"



set :jenkins_host, 'http://localhost:8080'

before 'deploy', 'jenkins:config_nodes'

```



config/deploy/staging.rb:

```xml

set :jenkins_template_vars, {

  :credential_id => 'STAGING-CREDENTIAL_ID'

}

```



config/deploy/production.rb:

```xml

set :jenkins_template_vars, {

  :credential_id => 'PRODUCTION-CREDENTIAL_ID'

}

```



### View Configuration



config directory structure(name your json file as a node name):

```

config

├── deploy.rb

└── jenkins

     └── views

         ├── view1.xml

         ├── view2.xml

         └── view3.xml

```



sample view configuration:

```xml



  view1

  false

  false

  

  

    

  

  

  

    

    

    

    

    

    

    

  

  job.*



```



deploy.rb:

```ruby

set :application, "your-awesome-app"

set :scm, :git

set :repository,  "https://github.com/your/repository.git"



set :jenkins_host, 'http://localhost:8080'

# set :jenkins_username, '' # default empty

# set :jenkins_password, '' # default empty

# set :jenkins_node_config_dir, 'config/jenkins/nodes'



before 'deploy', 'jenkins:config_views'

```



## Don't know how to write config.xml?



First, create the job, node, or view you want to manage with via the Jenkins UI.

Then, runnning following command to download them:



```

# For the job

curl -o config/jenkins/jobs/.xml http://jenkins.example.org/job//config.xml



# For the node

curl -o config/jenkins/nodes/.xml http://jenkins.example.org/computer//config.xml



# For the view

curl -o config/jenkins/views/.xml http://jenkins.example.org/view//config.xml

```



## Known Issues



### Using mutlibyte characters in config.xml



Until [jenkins_api_client PR143](https://github.com/arangamani/jenkins_api_client/pull/143) merged,

put following code to your Gemfile:



```ruby

# FIXME after https://github.com/arangamani/jenkins_api_client/pull/143 merged

gem 'jenkins_api_client', github: 'cynipe/jenkins_api_client', branch: 'fix-multibyte-configs'

```



## TODO



  * [ ] Reverse config support. something like `cap jenkins:reverse_job`

  * [ ] CI cucumber tests on Wercker

  * [ ] Capistrano v3 support

  * [ ] Make examples triable on user's local

  * [ ] Collect usage report using Google Analytics to see who uses this tool.



## Release Notes



### 0.1.2

  * Fix `.` is not allowed for job/node/view name ([#11](https://github.com/cynipe/jenkins-capistrano/pull/11))



### 0.1.1

  * Abort when json file found in node config and show user-friendly message

  * Remove unimplemented `jenkin:reverse_config` task



### 0.1.0

  * **[INCOMPATIBLE CHANGE]** Remove plugin support

  * **[INCOMPATIBLE CHANGE]** Change node configuration to use config.xml instead of json config

  * Support erb template for config.xml(need to name the file xxx.xml.erb)



### 0.0.7

  * Fix disable_job is not working with recent version of Jenkins ([#9](https://github.com/cynipe/jenkins-capistrano/pull/9))



### 0.0.6

  * Support view management ([726ad3ef](