jira-ruby 1.1.3 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 72616e61b52a45892a4fa86713ca5c9847440c42
-  data.tar.gz: 7aae22f02bcf7c91bb0dff21e5d55aa3ba828eee
+SHA256:
+  metadata.gz: 113ad755633d6eb87e63d7a97d3228f6649828547c01dee1ae1900ef0d575e2d
+  data.tar.gz: d59620f52976814ee7db58df10213bdb512f042a8b8214789ed07288f2899b65
 SHA512:
-  metadata.gz: a9b54e4bd78bb5aef39937772720382c79c221caa7bcfa711dd7a3eddd80f047b60d51874bb61ecd4489a28030f840125bbb713c7e75aa5e75a24f6017f7b76f
-  data.tar.gz: 66bbc3c25c56c03d37a00ffa38d520c8842f50e614ae96007b8202c0050cd8954189cf97e3ba62dcbb7ca9f0a8092815d723f2dc078ec126a0aab72bba5c4a33
+  metadata.gz: e523698732b5cef8a220259ccf5c42c568ac7eea435ee2ed2f2018cdd25959597d23337a67fac037e00be85a8838d9d32a2c79a156da008380699d2c9529cb03
+  data.tar.gz: cefe63455cb070951d73420dc1144b0c0a4651836427f507d218d3eb0780936e6a740842f6f2df8f68b14be8034bb196b4f5069d21ac0c3cd9e2a4292e43b456

data/.gitignore

@@ -8,3 +8,6 @@ pkg/*
 *.pem
 .DS_STORE
 doc
+.ruby-version
+
+.rakeTasks

data/.travis.yml

@@ -1,7 +1,9 @@
 language: ruby
 rvm:
-    - 2.3.1
-    - ruby-head
+    - 2.4
+    - 2.5
+    - 2.6
+    - 2.7
 before_script:
     - rake jira:generate_public_cert
-script: bundle exec rake spec
+script: bundle exec rake spec

data/Gemfile

@@ -1,8 +1,14 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
 
 group :development do
+  gem 'guard'
+  gem 'guard-rspec'
   gem 'wdm', '>= 0.1.0' if Gem.win_platform?
 end
 
+group :development, :test do
+  gem 'pry' # this was in the original Gemfile - but only needed in development & test
+end
+
 # Specify your gem's dependencies in jira_api.gemspec
 gemspec

data/Guardfile

@@ -6,7 +6,7 @@ guard 'rspec', cmd: 'bundle exec rspec --color --format doc' do
   watch(%r{^lib/(.+).rb$}) do |m|
     "spec/#{m[1]}_spec.rb"
   end
- 
+
   # watch /spec/ files
   watch(%r{^spec/(.+).rb$}) do |m|
     "spec/#{m[1]}.rb"

data/README.md

@@ -0,0 +1,452 @@
+# JIRA API Gem
+
+[![Code Climate](https://codeclimate.com/github/sumoheavy/jira-ruby.svg)](https://codeclimate.com/github/sumoheavy/jira-ruby)
+[![Build Status](https://travis-ci.org/sumoheavy/jira-ruby.svg?branch=master)](https://travis-ci.org/sumoheavy/jira-ruby)
+
+This gem provides access to the Atlassian JIRA REST API.
+
+## Slack
+
+Join our Slack channel! You can find us [here](https://jira-ruby-slackin.herokuapp.com/)
+
+## Example usage
+
+```ruby
+require 'rubygems'
+require 'jira-ruby'
+
+options = {
+  :username     => 'username',
+  :password     => 'pass1234',
+  :site         => 'http://mydomain.atlassian.net:443/',
+  :context_path => '',
+  :auth_type    => :basic
+}
+
+client = JIRA::Client.new(options)
+
+project = client.Project.find('SAMPLEPROJECT')
+
+project.issues.each do |issue|
+  puts "#{issue.id} - #{issue.summary}"
+end
+```
+
+## Links to JIRA REST API documentation
+
+* [Overview](https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs)
+
+* [Reference](http://docs.atlassian.com/jira/REST/latest/)
+
+## Running tests
+
+Before running tests, you will need a public certificate generated.
+
+```shell
+rake jira:generate_public_cert
+```
+
+## Setting up the JIRA SDK
+
+On Mac OS,
+
+* Follow the instructions under "Mac OSX Installer" here: https://developer.atlassian.com/server/framework/atlassian-sdk/install-the-atlassian-sdk-on-a-linux-or-mac-system
+* From within the archive directory, run:
+
+```shell
+./bin/atlas-run-standalone --product jira
+```
+
+Once this is running, you should be able to connect to
+http://localhost:2990/ and login to the JIRA admin system using `admin:admin`
+
+You'll need to create a dummy project and probably some issues to test using
+this library.
+
+## Configuring JIRA to use OAuth
+
+From the JIRA API tutorial
+
+> The first step is to register a new consumer in JIRA. This is done through
+> the Application Links administration screens in JIRA. Create a new
+> Application Link.
+> [Administration/Plugins/Application Links](http://localhost:2990/jira/plugins/servlet/applinks/listApplicationLinks)
+>
+> When creating the Application Link use a placeholder URL or the correct URL
+> to your client (e.g. `http://localhost:3000`), if your client can be reached
+> via HTTP and choose the Generic Application type. After this Application Link
+> has been created, edit the configuration and go to the incoming
+> authentication configuration screen and select OAuth. Enter in this the
+> public key and the consumer key which your client will use when making
+> requests to JIRA.
+
+This public key and consumer key will need to be generated by the Gem user, using OpenSSL
+or similar to generate the public key and the provided rake task to generate the consumer
+key.
+
+> After you have entered all the information click OK and ensure OAuth authentication is
+> enabled.
+
+For 2 legged oauth in server mode only, not in cloud based JIRA, make sure to `Allow 2-Legged OAuth`
+
+## Configuring JIRA to use HTTP Basic Auth
+
+Follow the same steps described above to set up a new Application Link in JIRA,
+however there is no need to set up any "incoming authentication" as this
+defaults to HTTP Basic Auth.
+
+## Configuring JIRA to use Cookie-Based Auth
+
+Jira supports cookie based authentication whereby user credentials are passed
+to JIRA via a JIRA REST API call.  This call returns a session cookie which must
+then be sent to all following JIRA REST API calls.
+
+To enable cookie based authentication, set `:auth_type` to `:cookie`,
+set `:use_cookies` to `true` and set `:username` and `:password` accordingly.
+
+```ruby
+require 'jira-ruby'
+
+options = {
+  :username           => 'username',
+  :password           => 'pass1234',
+  :site               => 'http://mydomain.atlassian.net:443/',
+  :context_path       => '',
+  :auth_type          => :cookie,  # Set cookie based authentication
+  :use_cookies        => true,     # Send cookies with each request
+  :additional_cookies => ['AUTH=vV7uzixt0SScJKg7'] # Optional cookies to send
+                                                   # with each request
+}
+
+client = JIRA::Client.new(options)
+
+project = client.Project.find('SAMPLEPROJECT')
+
+project.issues.each do |issue|
+  puts "#{issue.id} - #{issue.summary}"
+end
+```
+
+Some authentication schemes might require additional cookies to be sent with
+each request.  Cookies added to the `:additional_cookies` option will be added
+to each request.  This option should be an array of strings representing each
+cookie to add to the request.
+
+Some authentication schemes that require additional cookies ignore the username
+and password sent in the JIRA REST API call.  For those use cases, `:username`
+and `:password` may be omitted from `options`.
+
+## Configuring JIRA to use Personal Access Tokens Auth
+If your JIRA system is configured to support Personal Access Token authorization, minor modifications are needed in how credentials are communicated to the server.  Specifically, the paremeters `:username` and `:password` are not needed.  Also, the parameter `:default_headers` is needed to contain the api_token, which can be obtained following the official documentation from [Atlassian](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).  Please note that the Personal Access Token can only be used as it is. If it is encoded (with base64 or any other encoding method) then the token will not work correctly and authentication will fail.
+
+```ruby
+require 'jira-ruby'
+
+# NOTE: the token should not be encoded
+api_token = API_TOKEN_OBTAINED_FROM_JIRA_UI
+
+options = {
+  :site               => 'http://mydomain.atlassian.net:443/',
+  :context_path       => '',
+  :username           => '<the email you sign-in to Jira>',
+  :password           => api_token,
+  :auth_type          => :basic
+}
+
+client = JIRA::Client.new(options)
+
+project = client.Project.find('SAMPLEPROJECT')
+
+project.issues.each do |issue|
+  puts "#{issue.id} - #{issue.summary}"
+end
+```
+## Using the API Gem in a command line application
+
+Using HTTP Basic Authentication, configure and connect a client to your instance
+of JIRA.
+
+Note: If your Jira install is hosted on [atlassian.net](atlassian.net), it will have no context
+path by default. If you're having issues connecting, try setting context_path
+to an empty string in the options hash.
+
+```ruby
+require 'rubygems'
+require 'pp'
+require 'jira-ruby'
+
+# Consider the use of :use_ssl and :ssl_verify_mode options if running locally
+# for tests.
+
+# NOTE basic auth no longer works with Jira, you must generate an API token, to do so you must have jira instance access rights. You can generate a token here: https://id.atlassian.com/manage/api-tokens
+
+# You will see JIRA::HTTPError (JIRA::HTTPError) if you attempt to use basic auth with your user's password
+
+username = "myremoteuser"
+api_token = "myApiToken"
+
+options = {
+            :username => username,
+            :password => api_token,
+            :site     => 'http://localhost:8080/', # or 'https://<your_subdomain>.atlassian.net/'
+            :context_path => '/myjira', # often blank
+            :auth_type => :basic,
+            :read_timeout => 120
+          }
+
+client = JIRA::Client.new(options)
+
+# Show all projects
+projects = client.Project.all
+
+projects.each do |project|
+  puts "Project -> key: #{project.key}, name: #{project.name}"
+end
+```
+
+## Using the API Gem in your Rails application
+
+Using oauth, the gem requires the consumer key and public certificate file (which
+are generated in their respective rake tasks) to initialize an access token for
+using the JIRA API.
+
+Note that currently the rake task which generates the public certificate
+requires OpenSSL to be installed on the machine.
+
+Below is an example for setting up a rails application for OAuth authorization.
+
+Ensure the JIRA gem is loaded correctly
+
+```ruby
+# Gemfile
+...
+gem 'jira-ruby', :require => 'jira-ruby'
+...
+```
+
+Add common methods to your application controller and ensure access token
+errors are handled gracefully
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+
+  rescue_from JIRA::OauthClient::UninitializedAccessTokenError do
+    redirect_to new_jira_session_url
+  end
+
+  private
+
+  def get_jira_client
+
+    # add any extra configuration options for your instance of JIRA,
+    # e.g. :use_ssl, :ssl_verify_mode, :context_path, :site
+    options = {
+      :private_key_file => "rsakey.pem",
+      :consumer_key => 'test'
+    }
+
+    @jira_client = JIRA::Client.new(options)
+
+    # Add AccessToken if authorised previously.
+    if session[:jira_auth]
+      @jira_client.set_access_token(
+        session[:jira_auth]['access_token'],
+        session[:jira_auth]['access_key']
+      )
+    end
+  end
+end
+```
+
+Create a controller for handling the OAuth conversation.
+
+```ruby
+# app/controllers/jira_sessions_controller.rb
+class JiraSessionsController < ApplicationController
+
+  before_filter :get_jira_client
+
+  def new
+    callback_url = 'http://callback'
+    request_token = @jira_client.request_token(oauth_callback: callback_url)
+    session[:request_token] = request_token.token
+    session[:request_secret] = request_token.secret
+
+    redirect_to request_token.authorize_url
+  end
+
+  def authorize
+    request_token = @jira_client.set_request_token(
+      session[:request_token], session[:request_secret]
+    )
+    access_token = @jira_client.init_access_token(
+      :oauth_verifier => params[:oauth_verifier]
+    )
+
+    session[:jira_auth] = {
+      :access_token => access_token.token,
+      :access_key => access_token.secret
+    }
+
+    session.delete(:request_token)
+    session.delete(:request_secret)
+
+    redirect_to projects_path
+  end
+
+  def destroy
+    session.data.delete(:jira_auth)
+  end
+end
+```
+
+Create your own controllers for the JIRA resources you wish to access.
+
+```ruby
+# app/controllers/issues_controller.rb
+class IssuesController < ApplicationController
+  before_filter :get_jira_client
+  def index
+    @issues = @jira_client.Issue.all
+  end
+
+  def show
+    @issue = @jira_client.Issue.find(params[:id])
+  end
+end
+```
+
+## Using the API Gem in your Sinatra application
+
+Here's the same example as a Sinatra application:
+
+```ruby
+require 'jira-ruby'
+class App < Sinatra::Base
+  enable :sessions
+
+  # This section gets called before every request. Here, we set up the
+  # OAuth consumer details including the consumer key, private key,
+  # site uri, and the request token, access token, and authorize paths
+  before do
+    options = {
+      :site               => 'http://localhost:2990/',
+      :context_path       => '/jira',
+      :signature_method   => 'RSA-SHA1',
+      :request_token_path => "/plugins/servlet/oauth/request-token",
+      :authorize_path     => "/plugins/servlet/oauth/authorize",
+      :access_token_path  => "/plugins/servlet/oauth/access-token",
+      :private_key_file   => "rsakey.pem",
+      :rest_base_path     => "/rest/api/2",
+      :consumer_key       => "jira-ruby-example"
+    }
+
+    @jira_client = JIRA::Client.new(options)
+    @jira_client.consumer.http.set_debug_output($stderr)
+
+    # Add AccessToken if authorised previously.
+    if session[:jira_auth]
+      @jira_client.set_access_token(
+        session[:jira_auth][:access_token],
+        session[:jira_auth][:access_key]
+      )
+    end
+  end
+
+
+  # Starting point: http://<yourserver>/
+  # This will serve up a login link if you're not logged in. If you are, it'll show some user info and a
+  # signout link
+  get '/' do
+    if !session[:jira_auth]
+      # not logged in
+      <<-eos
+        <h1>jira-ruby (JIRA 5 Ruby Gem) demo </h1>You're not signed in. Why don't you
+        <a href=/signin>sign in</a> first.
+      eos
+    else
+      #logged in
+      @issues = @jira_client.Issue.all
+
+      # HTTP response inlined with bind data below...
+      <<-eos
+        You're now signed in. There #{@issues.count == 1 ? "is" : "are"} #{@issues.count}
+        issue#{@issues.count == 1 ? "" : "s"} in this JIRA instance. <a href='/signout'>Signout</a>
+      eos
+    end
+  end
+
+  # http://<yourserver>/signin
+  # Initiates the OAuth dance by first requesting a token then redirecting to
+  # http://<yourserver>/auth to get the @access_token
+  get '/signin' do
+    callback_url = "#{request.base_url}/callback"
+    request_token = @jira_client.request_token(oauth_callback: callback_url)
+    session[:request_token] = request_token.token
+    session[:request_secret] = request_token.secret
+
+    redirect request_token.authorize_url
+  end
+
+  # http://<yourserver>/callback
+  # Retrieves the @access_token then stores it inside a session cookie. In a real app,
+  # you'll want to persist the token in a datastore associated with the user.
+  get "/callback" do
+    request_token = @jira_client.set_request_token(
+      session[:request_token], session[:request_secret]
+    )
+    access_token = @jira_client.init_access_token(
+      :oauth_verifier => params[:oauth_verifier]
+    )
+
+    session[:jira_auth] = {
+      :access_token => access_token.token,
+      :access_key => access_token.secret
+    }
+
+    session.delete(:request_token)
+    session.delete(:request_secret)
+
+    redirect "/"
+  end
+
+  # http://<yourserver>/signout
+  # Expires the session
+  get "/signout" do
+    session.delete(:jira_auth)
+    redirect "/"
+  end
+end
+```
+
+## Using the API Gem in a 2 legged context
+
+Here's an example on how to use 2 legged OAuth:
+```ruby
+require 'rubygems'
+require 'pp'
+require 'jira-ruby'
+
+options = {
+            :site               => 'http://localhost:2990/',
+            :context_path       => '/jira',
+            :signature_method   => 'RSA-SHA1',
+            :private_key_file   => "rsakey.pem",
+            :rest_base_path     => "/rest/api/2",
+            :auth_type => :oauth_2legged,
+            :consumer_key       => "jira-ruby-example"
+          }
+
+client = JIRA::Client.new(options)
+
+client.set_access_token("","")
+
+# Show all projects
+projects = client.Project.all
+
+projects.each do |project|
+  puts "Project -> key: #{project.key}, name: #{project.name}"
+end
+```

data/Rakefile

@@ -6,25 +6,24 @@ require 'rdoc/task'
 
 Dir.glob('lib/tasks/*.rake').each { |r| import r }
 
-task :default => [:test]
+task default: [:test]
 
-task :test => [:prepare, :spec]
+task test: %i[prepare spec]
 
 desc 'Prepare and run rspec tests'
 task :prepare do
   rsa_key = File.expand_path('rsakey.pem')
-  unless File.exists?(rsa_key)
-    raise 'rsakey.pem does not exist, tests will fail.  Run `rake jira:generate_public_cert` first'
+  unless File.exist?(rsa_key)
+    Rake::Task['jira:generate_public_cert'].invoke
   end
 end
 
 desc 'Run RSpec tests'
-#RSpec::Core::RakeTask.new(:spec)
-RSpec::Core::RakeTask.new(:spec) do |task|
+# RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec, [] => [:prepare]) do |task|
   task.rspec_opts = ['--color', '--format', 'doc']
 end
 
-
 Rake::RDocTask.new(:doc) do |rd|
   rd.main       = 'README.rdoc'
   rd.rdoc_dir   = 'doc'

data/example.rb

@@ -59,11 +59,12 @@ old_way = issue.customfield_12345
 new_way = issue.Special_Field
 (old_way == new_way) && puts 'much easier'
 #
-# Can also use this to specify fields to be returned in the response
-client.Issue.jql(a_normal_jql_search, fields:[:Special_Field])
-# Or you could always do it the old way - if you can remember the numbers...
-client.Issue.jql(a_normal_jql_search, fields:['customfield_12345'])
-# You can specify the maximum number of results to be returned in the response, i.e. 500
+# You can also specify fields to be returned in the response
+# This is especially useful in regards to shortening JQL query response times if performance becomes an issue
+client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :Special_field, :created])
+# Or you could always do it the old way - if you can remember the custom field numbers...
+client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :customfield_1234, :created])
+# You can also specify the maximum number of results to be returned in the response, i.e. 500
 client.Issue.jql(a_normal_jql_search, max_results: 500)
 
 # # Find a specific project by key
@@ -98,7 +99,16 @@ client.Issue.jql(a_normal_jql_search, max_results: 500)
 # # Create an issue
 # # ---------------
 # issue = client.Issue.build
-# issue.save({"fields"=>{"summary"=>"blarg from in example.rb","project"=>{"id"=>"10001"},"issuetype"=>{"id"=>"3"}}})
+# labels = ['label1', 'label2']
+# issue.save({
+#   "fields" => {
+#     "summary"   => "blarg from in example.rb",
+#     "project"   => {"key" => "SAMPLEPROJECT"},
+#     "issuetype" => {"id" => "3"},
+#     "labels"    => labels,
+#     "priority"  => {"id" => "1"}
+#   }
+# })
 # issue.fetch
 # pp issue
 #
@@ -108,11 +118,25 @@ client.Issue.jql(a_normal_jql_search, max_results: 500)
 # issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA!"}})
 # pp issue
 #
+# # Transition an issue
+# # -------------------
+# issue_transition = issue.transitions.build
+# issue_transition.save!('transition' => {'id' => transition_id})
+#
+# # Change assignee
+# # -------------------
+# issue.save({'fields' => {'assignee' => {'name' => person_name}}})
+#
 # # Find a user
 # # -----------
 # user = client.User.find('admin')
 # pp user
 #
+# # Get all issue watchers
+# # ----------------------
+# issue = client.Issue.find("10002")
+# watchers = issue.watchers.all
+# watchers = client.Watcher.all(:issue => issue)
 # # Get all issue types
 # # -------------------
 # issuetypes = client.Issuetype.all
@@ -142,6 +166,14 @@ client.Issue.jql(a_normal_jql_search, max_results: 500)
 # # --------------------------
 # issue.comments.first.save({"body" => "an updated comment frome example.rb"})
 
+
+# # Add attachment to Issue
+# # ------------------------
+#  issue = client.Issue.find('PROJ-1')
+#  attachment = issue.attachments.build
+#  attachment.save('file': '/path/to/file')
+#
+
 # List all available link types
 # ------------------------------
 pp client.Issuelinktype.all

data/http-basic-example.rb

@@ -2,29 +2,30 @@ require 'rubygems'
 require 'pp'
 require 'jira-ruby'
 
-if ARGV.length == 0
+if ARGV.empty?
   # If not passed any command line arguments, prompt the
   # user for the username and password.
-  puts "Enter the username: "
+  puts 'Enter the username: '
   username = gets.strip
 
-  puts "Enter the password: "
+  puts 'Enter the password: '
   password = gets.strip
 elsif ARGV.length == 2
-  username, password = ARGV[0], ARGV[1]
+  username = ARGV[0]
+  password = ARGV[1]
 else
   # Script must be passed 0 or 2 arguments
-  raise "Usage: #{$0} [ username password ]"
+  raise "Usage: #{$PROGRAM_NAME} [ username password ]"
 end
 
 options = {
-            :username => username,
-            :password => password,
-            :site     => 'http://localhost:8080/',
-            :context_path => '',
-            :auth_type => :basic,
-            :use_ssl => false
-          }
+  username: username,
+  password: password,
+  site: 'http://localhost:8080/',
+  context_path: '',
+  auth_type: :basic,
+  use_ssl: false
+}
 
 client = JIRA::Client.new(options)
 
@@ -51,7 +52,7 @@ end
 #
 # # List issues by JQL query
 # # ------------------------
-# client.Issue.jql('PROJECT = "SAMPLEPROJECT"', [comments, summary]).each do |issue|
+# client.Issue.jql('PROJECT = "SAMPLEPROJECT"', {fields: %w(summary status)}).each do |issue|
 #   puts "#{issue.id} - #{issue.fields['summary']}"
 # end
 #