jenkins2 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89eb3788e74b3dca921bb2f0cbe47532563fda46
-  data.tar.gz: e1f46c1ccabb5c259cc650dc9cdf1041ca627429
+  metadata.gz: 89372ed31079640dc0d1e310f3cb279c209846f3
+  data.tar.gz: 2ff0f1d37148a71cede4a61ffd9fb9dca76edaa5
 SHA512:
-  metadata.gz: dd24ec55acd234fa995b76b35a826a67058fc59df0f4cec26319780bcfce28547f955f39ebc4b598a365c0a06429fca2598868eb8b2198fceea33ae01e5f5e55
-  data.tar.gz: 9743457399f767bba6cea77a0e7d61bafd9207ca5da14fac17891f6230256984bc6c545f5236a48c80008f7000339e01a5cf2770ca2f950714c0ce58fe7cd0a1
+  metadata.gz: 28f396b6e2f8dbaf2f2e0f8ff6b222677d0e405b264af0f97c01d8ddd4ea34c3b53577ce555a31f5810b10b4ad47444c741a7a77db578caa773f69ed8f896461
+  data.tar.gz: c53ee77163b15abe3cdc5bc14b24d408d6c51faf8d8b768e8e4f5f499b97db7d420c020a6c4c1bd874eed030568b60ffa6c2292a932bffe41a20bc0ee216b810

data/CHANGELOG.md

@@ -1,31 +1,52 @@
 # Change Log
 
-## [v0.1.0](https://bitbucket.org/DracoAter/jenkins2/commits/tag/v0.1.0) (2017-10-11)
+## [v1.0.0](https://bitbucket.org/DracoAter/jenkins2/commits/tag/v1.0.0) (February 19, 2018)
+
+### Tested With
+
+- Jenkins 2.89.4
+	- ssh-credentials 1.13
+	- plain-credentials 1.4
+	- command-launcher 1.2
+
+### Enhancements
+
+- Completely refactored API and CLI.
+- Log will write to stderr by default (instead of stdout).
+- Can create/show/update/delete Views.
+- Can create/show/update/delete Jobs.
+- Can show existing Users, People.
+- Can install plugin from file/url.
+- Code is now checked with rubocop.
+- Switched configuration file format to yaml.
+- Integration tests are now run on bitbucket pipelines.
+
+## [v0.1.0](https://bitbucket.org/DracoAter/jenkins2/commits/tag/v0.1.0) (October 11, 2017)
 
 ### Enhancements
 
-- Support Crumbs
-- Can forcefully restart Jenkins
+- Support Crumbs.
+- Can forcefully restart Jenkins.
 
-## [v0.0.2](https://bitbucket.org/DracoAter/jenkins2/commits/tag/v0.0.2) (2016-10-25)
+## [v0.0.2](https://bitbucket.org/DracoAter/jenkins2/commits/tag/v0.0.2) (October 25, 2016)
 
 ### Enhancements
 
-- Hopefully this gem is now usable
-- Get Jenkins version
-- Prepare for / cancel Jenkins shutdown
-- Wait for all nodes to be idle
-- Set node temporarily offline / online
-- Connect / Disconnect node
-- Wait for node to become idle, check if node is idle
-- Get node definition as XML
-- Update node definition from XML
-- Run [parameterized] build
-- List installed plugins
-- Install / uninstall a plugin by short name (i.e. ssh-credentials)
-- Create username with password credential ( Requires credentials plugin on Jenkins )
-- Create ssh username with private key credential ( Requires ssh-credentials plugin on Jenkins )
-- Create secret string credential ( Requires plain-credentials plugin on Jenkins )
-- Create secret file credential ( Requires plain-credentials plugin on Jenkins )
-- Get credential by id
-- List credentials
+- Hopefully this gem is now usable.
+- Get Jenkins version.
+- Prepare for / cancel Jenkins shutdown.
+- Wait for all nodes to be idle.
+- Set node temporarily offline / online.
+- Connect / Disconnect node.
+- Wait for node to become idle, check if node is idle.
+- Get node definition as XML.
+- Update node definition from XML.
+- Run [parameterized] build.
+- List installed plugins.
+- Install / uninstall a plugin by short name (i.e. ssh-credentials).
+- Create username with password credential ( Requires credentials plugin on Jenkins ).
+- Create ssh username with private key credential ( Requires ssh-credentials plugin on Jenkins ).
+- Create secret string credential ( Requires plain-credentials plugin on Jenkins ).
+- Create secret file credential ( Requires plain-credentials plugin on Jenkins ).
+- Get credential by id.
+- List credentials.

data/README.md

@@ -1,121 +1,185 @@
 # Jenkins2
 
-Jenkins2 gem is a command line interface and API client for Jenkins 2 CI Server. This gem has been
-tested with Jenkins 2.19.1 LTS.
-
-# Features available
-## Global
-- Get Jenkins version
-- Prepare for shutdown
-- Cancel shutdown
-- Wait for all nodes to be idle
-
-## Node
-- Set node temporarily offline / online
-- Connect / Disconnect node
-- Wait for node to become idle
-- Get node definition as XML
-- Update node definition from XML
-
-## Job
-- Run [parameterized] build
-
-## Plugin
-- List installed plugins
-- Install / uninstall a plugin by short name (i.e. ssh-credentials)
+Jenkins2 gem is a command line interface and API client for Jenkins 2 CI Server. This gem is
+tested with latest Jenkins LTS. (See the [CHANGELOG](CHANGELOG.md) for exact versions.)
 
+## Features available
 
-## Credentials
-- Create username with password credential ( Requires credentials plugin on Jenkins )
-- Create ssh username with private key credential ( Requires ssh-credentials plugin on Jenkins )
-- Create secret string credential ( Requires plain-credentials plugin on Jenkins )
-- Create secret file credential ( Requires plain-credentials plugin on Jenkins )
-- Get credential by id
-- List credentials
+### Global
 
-# Installation
+- Jenkins version
+- Quiet Down
+- Cancel Quiet Down
+- Safe Restart
+- Immediate Restart
 
-    gem install jenkins2
+### Users / People
 
-# Configuration
+- Get authenticated user (who-am-i)
 
-The gem does not require any configuration. However, if your Jenkins is secured you will have to
-provide credentials with every CLI call.
+### Node / Slave / Computer
 
-    jenkins2 -s http://jenkins.example.com -u admin -k mysecretkey offline-node -n mynode
+- Create slave from config.xml
+- Delete slave
+- Toggle slave offline / online
+- Launch slave agent
+- Disconnect slave
+- Get slave's config.xml
+- List \[online\] slaves
+- Get slave(s) states
 
-This can be avoided by creating a json configuration file like this
+### Plugins
 
-    {
-      "server": "http://jenkins.example.com",
-      "user": "admin",
-      "key": "mysecretkey"
-    }
+- List installed plugins
+- Install a plugin and its dependencies from update center (providing a short name e.g.
+thinBackup).
+- Install a plugin either from a file or an URL. Dependencies are not installed!
+- Show plugin information
+- Uninstall a plugin
+
+### Credentials
+
+- Create username with password credentials (Requires credentials plugin on Jenkins)
+- Create ssh username with private key credentials (Requires ssh-credentials plugin on Jenkins)
+- Create secret string credentials (Requires plain-credentials plugin on Jenkins)
+- Create secret file credentials (Requires plain-credentials plugin on Jenkins)
+- Get credentials by id
+- Delete credentials
+- List credentials in particular store and domain
+
+### Views
+
+- List views
+- Get view configuraiton xml
+- Update view configuraiton xml
+- Create View
+- Delete View
+- Add job to view
+- Remove job from view
+
+### Jobs
+
+- List jobs
+- Create job from config.xml or by copying another one
+- Set (Update) job's config.xml
+- Get job's config.xml
+- Delete job
+- Enable, disable job
+- Run build (with parameters, if required)
+
+## Installation
+
+```sh
+$ gem install jenkins2
+```
+
+## Usage
 
-By default Jenkins2 expects this file to be at ~/.jenkins2.json, but you can provide your own path
-with --config-file switch. This way the above mentioned command will be much shorter.
+Either run it from command line:
 
-    jenkins2 -c offline-node -n mynode # => -c switch tells Jenkins2 to read configuration file
+```sh
+$ jenkins2 -s http://jenkins.example.com offline-node -n mynode
+$ jenkins2 --help # => for help and list of available commands
+$ jenkins2 --help <command> # => for help on particular command
+```
 
-# Usage
+Or use it in your ruby code:
 
-Either run it from command line:
+```ruby
+require 'jenkins2'
 
-    jenkins2 -s http://jenkins.example.com offline-node -n mynode
-    jenkins2 --help # => for help and list of available commands
-    jenkins2 --help <command> # => for help on particular command
+jc = Jenkins2.connect(server: 'http://jenkins.example.com', user: 'admin', key:  'mysecretkey')
+jc.version
+jc.computer('mynode').toggle_offline( 'Some reason, why' )
+```
 
-Or use it in your ruby code:
+## Configuration
+
+The gem does not require any configuration. However, if your Jenkins is secured you will have to
+provide credentials with every CLI call.
+
+```sh
+$ jenkins2 -s http://jenkins.example.com -u admin -k mysecretkey offline-node -n mynode
+```
+
+This can be avoided by creating a yaml configuration file like this
+
+```yaml
+---
+:server: http://jenkins.example.com
+:user: admin
+:key: mysecretkey
+:verbose: 3
+:log: /var/log/jenkins2.log
+```
+
+and putting global options there. Jenkins will not read the file unless you use `-c` or
+`--config-file` switches. If you use the switch, but omit the file path, the gem will look for
+`.jenkins2.conf` in current directory.
+
+This way the above mentioned command is much shorter
 
-    require 'jenkins2'
-    jc = Jenkins2::Client.new( server: 'http://jenkins.example.com' )
-    jc.version
-    jc.offline_node( node: 'mynode' )
+```sh
+$ jenkins2 -c offline-node -n mynode # => -c switch tells Jenkins2 to read .jenkins2.conf file
+```
 
-# License
+## License
 
 MIT - see the accompanying [LICENSE](LICENSE) file for details.
 
-# Changelog
+## Changelog
 
 To see what has changed in recent versions see the [CHANGELOG](CHANGELOG.md).
 Jenkins2 gem follows the [Semantic Versioning Policy](http://guides.rubygems.org/patterns).
 
-# Contributing
+## Contributing
 
 Additional commands and bugfixes are welcome! Please fork and submit a pull request on an
-individual branch per change. The project follows GitHub Script
+individual branch per change. The project has a script folder which is inspired by GitHub Script
 ["Scripts To Rule Them All"] (https://github.com/github/scripts-to-rule-them-all) pattern.
 
-## Bootstrap
+### Bootstrap
 
 After cloning the project, run:
 
-    script/bootstrap
+```sh
+$ script/bootstrap
+```
 
 to download gem and other dependencies (currently tested only on ubuntu xenial).
 
-## Tests
+### Tests
 
-The project is expected to be heavily tested :) with unit and integratin tests. To run unit tests,
-you will need to have some gems installed (see jenkins2.gemspec -> development\_dependencies or
-run bootstrap script). To run unit tests run
+The project is expected to be heavily tested :) with unit and integratin tests.
+Integration tests are run against a Jenkins server. Currently Jenkins server is set up in docker
+container. To run all the tests (unit and integration ) type:
 
-    script/unit_test
+```sh
+$ script/test
+```
 
-Integration tests are run against a Jenkins server. Currently they require an lxd to setup it.
-To run integration tests type
+This will start Jenkins in docker container, run the tests and then kill the container. If you
+want to just start the Jenkins in docker and then may be run tests several times against it, you
+can do the following:
 
-    script/integration_test
+```sh
+$ source script/jenkins_start # start jenkins
+$ rake test:all # run all tests
+```
+Then, when you have finished running tests, run `script/jenkins_kill` to stop Jenkins in docker.
 
-This will start Jenkins in lxd container, run the tests and then kill the container.
+If you want to run just unit tests, you can do it through rake task:
 
-## Continuous Integration
+```sh
+$ rake test:unit
+```
+provided you have already installed all the dependences (see [jenkins2.gemspec](jenkins2.gemspec)
+-> development\_dependencies or run [bootstrap script](script/bootstrap)).
 
-If you would like to automate test runs the progect already has [Jenkinsfile](Jenkinsfile) for
-quick and easy integration with Jenkins Pipelines. If you are using another CI server, just make
-sure it runs
+### Continuous Integration
 
-    script/cibuild
+The project uses Bitbucket Pipelines as CI environment. You can check out
+[bitbucket-pipelines.yml](bitbucket-pipelines.yml) for the exact script.
 
-and then collects the data from the generated reports.
+Also there is a [Jenkinsfile](Jenkinsfile) for quick and easy integration with Jenkins Pipelines.
+Unfortunately it is outdated now, but it can be still used as an example to start from.

data/bin/jenkins2

@@ -1,4 +1,11 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require_relative '../lib/jenkins2'
-Jenkins2::CommandLine.new( ARGV ).run
+
+result = Jenkins2::CLI.new.parse(ARGV).call
+if result.is_a? String
+	puts result
+elsif !result
+	exit 1
+end

data/lib/jenkins2.rb

@@ -1,5 +1,10 @@
-require_relative 'jenkins2/command_line'
-require_relative 'jenkins2/version'
-require_relative 'jenkins2/log'
-require_relative 'jenkins2/try'
-require_relative 'jenkins2/wait'
+# frozen_string_literal: true
+
+require_relative 'jenkins2/api'
+require_relative 'jenkins2/cli'
+
+module Jenkins2
+	def self.connect(**opts)
+		Jenkins2::API.new opts
+	end
+end

data/lib/jenkins2/api.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'resource_proxy'
+require_relative 'connection'
+require_relative 'errors'
+require_relative 'util'
+require_relative 'api/credentials'
+require_relative 'api/computer'
+require_relative 'api/job'
+require_relative 'api/plugins'
+require_relative 'api/root'
+require_relative 'api/user'
+require_relative 'api/view'
+
+module Jenkins2
+	class API
+		include Credentials
+		include Computer
+		include Job
+		include Plugins
+		include Root
+		include User
+		include View
+
+		attr_reader :connection
+
+		def initialize(**options)
+			@connection = Jenkins2::Connection.new(options[:server]).
+				basic_auth options[:user], options[:key]
+			Log.init(log: options[:log], verbose: options[:verbose])
+		end
+	end
+end

data/lib/jenkins2/api/computer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'rud'
+
+require 'cgi'
+
+module Jenkins2
+	class API
+		module Computer
+			def computer(id=nil, **params)
+				proxy = Proxy.new connection, 'computer', params
+				proxy.id = id
+				proxy
+			end
+
+			class Proxy < ::Jenkins2::ResourceProxy
+				attr_accessor :id
+				include ::Jenkins2::API::RUD
+
+				def launch_agent
+					connection.post(build_path('launchSlaveAgent')).code == '302'
+				end
+
+				def create
+					form_data = { name: @id, type: 'hudson.slaves.DumbSlave$DescriptorImpl', json: '{}' }
+					@id = nil
+					path = build_path 'doCreateItem'
+					connection.post(path, ::URI.encode_www_form(form_data)).code == '302'
+				end
+
+				def disconnect(offline_message=nil)
+					path = build_path 'doDisconnect'
+					body = "offlineMessage=#{::CGI.escape offline_message}" unless offline_message.nil?
+					connection.post(path, body).code == '302'
+				end
+
+				def toggle_offline(offline_message=nil)
+					path = build_path 'toggleOffline'
+					body = "offlineMessage=#{::CGI.escape offline_message}" unless offline_message.nil?
+					connection.post(path, body).code == '302'
+				end
+
+				def online?
+					not ( offline or temporarilyOffline)
+				end
+			end
+		end
+	end
+end