Jenkins Launcher

Command line interface for performing continuous integration on Jenkins CI with Travis CI like configuration management

Download .zip Download .tar.gz View on GitHub

Jenkins Launcher

Overview:

Jenkins launcher makes use of the 'jenkins_api_client' Rubygem which is an API client/wrapper written in pure Ruby and makes use of the Jenkins's JSON API. This project mainly focusses on performing continuous integration tests on a remote Jenkins CI server and all activities are achieved through a command line interface. This projects acts much like building on Travis CI, but makes use of your organization's own Jenkins server where you may have specialized configuration or you don't want to expose your results publicly.

Installation:

gem install jenkins_launcher

Getting Started:

Jenkins credentials:

Please checkout the README.md of the Jenkins API client project for setting up credentials for easy access.

Command line interface:

This Rubygem installs a command jlaunch when this gem gets installed.

Simply running the command on your terminal will show all available commands and options available.

Kannans-MacBook-Pro:~ kannanmanickam$ jlaunch 
Tasks:
  jlaunch attach CONFIG   # Attach to already running build if any
  jlaunch create CONFIG   # Load configuration and create a job on jenkins
  jlaunch destroy CONFIG  # Destroy the job from Jenkins server
  jlaunch help [TASK]     # Describe available tasks or one specific task
  jlaunch start CONFIG    # Load configuration, create job on jenkins, and build
  jlaunch stop CONFIG     # Stop already running build of the job
  jlaunch version         # Shows current version

Options:
  -u, [--username=USERNAME]                # Name of Jenkins user
  -p, [--password=PASSWORD]                # Password of Jenkins user
  -b, [--password-base64=PASSWORD_BASE64]  # Base 64 encoded password of Jenkins user
  -s, [--server-ip=SERVER_IP]              # Jenkins server IP address
  -o, [--server-port=SERVER_PORT]          # Jenkins server port
  -c, [--creds-file=CREDS_FILE]            # Credentials file for communicating with Jenkins server

Create command:

The create command loads the configuration from your configuration file and creates the job on the Jenkins server if it is not already created. Pleas use some unique name for the job. Typing jlaunch help create will show the help page for the create command.

Kannans-MacBook-Pro:~ kannanmanickam$ jlaunch help create
Usage:
  jlaunch create CONFIG

Options:
  -u, [--username=USERNAME]                # Name of Jenkins user
  -p, [--password=PASSWORD]                # Password of Jenkins user
  -b, [--password-base64=PASSWORD_BASE64]  # Base 64 encoded password of Jenkins user
  -s, [--server-ip=SERVER_IP]              # Jenkins server IP address
  -o, [--server-port=SERVER_PORT]          # Jenkins server port
  -c, [--creds-file=CREDS_FILE]            # Credentials file for communicating with Jenkins server

Load configuration and create a job on jenkins

Start command:

The start command will create the job if it is not already there and also start a build of the job. Typing jlaunch help start will show the help page for this command.

Kannans-MacBook-Pro:~ kannanmanickam$ jlaunch help start
Usage:
  jlaunch start CONFIG

Options:
  -q, [--quiet-period=QUIET_PERIOD]        # Jenkins Quit period to wait before starting to get console output. Default is '5' seconds
  -r, [--refresh-rate=REFRESH_RATE]        # Time to wait between getting console output from server. Default is '5' seconds
  -d, [--delete-after]                     # Delete the job from Jenkins after the build is finished
  -u, [--username=USERNAME]                # Name of Jenkins user
  -p, [--password=PASSWORD]                # Password of Jenkins user
  -b, [--password-base64=PASSWORD_BASE64]  # Base 64 encoded password of Jenkins user
  -s, [--server-ip=SERVER_IP]              # Jenkins server IP address
  -o, [--server-port=SERVER_PORT]          # Jenkins server port
  -c, [--creds-file=CREDS_FILE]            # Credentials file for communicating with Jenkins server

Load configuration, create job on jenkins, and build

The start command accepts three other options:

  1. --quiet-period: This is the quiet period of the jenkins server to wait after the build is scheduled. The default is 5 seconds. This command will wait for the specified seconds to get the console output after the build is scheduled.
  2. --refresh-rate: This is the rate for pinging the Jenkins API to get the console output. The default for this is set to 5 seconds. This is the default in the Jenkins UI as well.
  3. --delete-after: If this boolean option is specified in the command, the job will be deleted from the Jenkins server after the build is finished. If for some reason the command line is interrupted, the job will not be deleted. The attach command should be run to attach to the running job. If the job is already finished and should be deleted, use the destroy command separately to delete the job.

Attach command:

The attach command is used for attaching to an already running build and to watch it's progress. Typing jlaunch help attach will show the help page for this command.

Kannans-MacBook-Pro:~ kannanmanickam$ jlaunch help attach
Usage:
  jlaunch attach CONFIG

Options:
  -r, [--refresh-rate=REFRESH_RATE]        # Time to wait between getting console output from server. Default is '5' seconds
  -d, [--delete-after]                     # Delete the job from Jenkins after the build is finished
  -u, [--username=USERNAME]                # Name of Jenkins user
  -p, [--password=PASSWORD]                # Password of Jenkins user
  -b, [--password-base64=PASSWORD_BASE64]  # Base 64 encoded password of Jenkins user
  -s, [--server-ip=SERVER_IP]              # Jenkins server IP address
  -o, [--server-port=SERVER_PORT]          # Jenkins server port
  -c, [--creds-file=CREDS_FILE]            # Credentials file for communicating with Jenkins server

Attach to already running build if any

This command also accepts the --refresh-rate and --delete-after options. See the start command for more details on this option.

Console command:

The console command just prints the console output from the most recent build of the job. Typing jlaunch help console will bring up the following help page.

Kannans-MacBook-Pro:~ kannanmanickam$ jlaunch help console
Usage:
  jlaunch console CONFIG

Options:
  -u, [--username=USERNAME]                # Name of Jenkins user
  -p, [--password=PASSWORD]                # Password of Jenkins user
  -b, [--password-base64=PASSWORD_BASE64]  # Base 64 encoded password of Jenkins user
  -s, [--server-ip=SERVER_IP]              # Jenkins server IP address
  -o, [--server-port=SERVER_PORT]          # Jenkins server port
  -c, [--creds-file=CREDS_FILE]            # Credentials file for communicating with Jenkins server

Show the console output of the recent build if any

Stop command:

The stop command stops running build of a job. Typing jlaunch help stop will show the help page for this command.

Kannans-MacBook-Pro:~ kannanmanickam$ jlaunch help stop
Usage:
  jlaunch stop CONFIG

Options:
  -u, [--username=USERNAME]                # Name of Jenkins user
  -p, [--password=PASSWORD]                # Password of Jenkins user
  -b, [--password-base64=PASSWORD_BASE64]  # Base 64 encoded password of Jenkins user
  -s, [--server-ip=SERVER_IP]              # Jenkins server IP address
  -o, [--server-port=SERVER_PORT]          # Jenkins server port
  -c, [--creds-file=CREDS_FILE]            # Credentials file for communicating with Jenkins server

Stop already running build of the job

Destroy command:

The destroy command will destroy the job created on the Jenkins server. This is usually used after all tests are ran and the job is not required anymore. Typing jlaunch help destroy will bring up the following help page.

Kannans-MacBook-Pro:~ kannanmanickam$ jlaunch help destroy
Usage:
  jlaunch destroy CONFIG

Options:
  -f, [--force]                            # Stop the job if it is already running
  -u, [--username=USERNAME]                # Name of Jenkins user
  -p, [--password=PASSWORD]                # Password of Jenkins user
  -b, [--password-base64=PASSWORD_BASE64]  # Base 64 encoded password of Jenkins user
  -s, [--server-ip=SERVER_IP]              # Jenkins server IP address
  -o, [--server-port=SERVER_PORT]          # Jenkins server port
  -c, [--creds-file=CREDS_FILE]            # Credentials file for communicating with Jenkins server

Destroy the job from Jenkins server

This command accepts a boolean option --force which forces the destroy command to stop any running build. If this option is not specified the command will exit without destroying the job or the stop command can be called separately to stop the build before calling this command.

Structure of the configuration YAML file:

The structure of the configuration file looks like this.

name: test_build_kannan
git: git://github.com/arangamani/jenkins_api_client.git
ref: master
node: slave1
script:
 - echo "first echo"
 - sleep 10
 - echo "second echo"
 - sleep 5

Configuration options:

  • name: Name is a required parameter and used for creating job on the Jenkins server.
  • node: Name of the node/slave where this job should run. If the node is not available in the Jenkins server, it will be skipped.
  • git: Git URL for checking out the project from. This requires that you need Git plugin installed on your Jenkins. If not, the job will be created without this source control.
  • svn: Subversion URL. If this option is specified, the Subversion URL will be used to checkout the project. Subversion is installed in Jenkins by default.
  • ref: This specifies the branch to checkout for Git source control system.
  • script: Shell command is the command executed on the server. Multiple lines of command can be given just like shown in the example.

Author:

Kannan Manickam arangamani.kannan@gmail.com

CONTRIBUTING:

If you would like to contribute to this project, just do the following:

  1. Fork the repo on Github.
  2. Add your features and make commits to your forked repo.
  3. Make a pull request to this repo.
  4. Review will be done and changes will be requested.
  5. Once changes are done or no changes are required, pull request will be merged.
  6. The next release will have your changes in it.

LICENCE:

Copyright (c) 2013 Kannan Manickam arangamani.kannan@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.