<img src=“https://codeclimate.com/github/sumoheavy/jira-ruby.png” /> <img src=“https://travis-ci.org/sumoheavy/jira-ruby.png?branch=master”
This gem provides access to the Atlassian JIRA REST API.
client = JIRA::Client.new({:consumer_key => CONSUMER_KEY, :consumer_secret => CONSUMER_SECRET})
project = client.Project.find('SAMPLEPROJECT')
project.issues.each do |issue|
puts "#{issue.id} - #{issue.summary}"
end
issue.comments.each {|comment| ... }
comment = issue.comments.build
comment.save({'body':'My new comment'})
comment.delete
On Mac OS,
-
Follow the instructions under “Mac OSX Installer” here: developer.atlassian.com/display/DOCS/Install+the+Atlassian+SDK+on+a+Linux+or+Mac+System
-
From within the archive directory, run:
./bin/atlas-run-standalone --product jira
Once this is running, you should be able to connect to 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.
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.
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.
Using HTTP Basic Authentication, configure and connect a client to your instance of JIRA.
require 'rubygems' require 'pp' require 'jira' # Consider the use of :use_ssl and :ssl_verify_mode options if running locally # for tests. username = "myremoteuser" password = "myuserspassword" options = { :username => username, :password => password, :site => 'http://localhost:8080/', :context_path => '/myjira', :auth_type => :basic } 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 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
# Gemfile ... gem 'jira-ruby', :require => 'jira' ...
Add common methods to your application controller and ensure access token errors are handled gracefully
# 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.
# app/controllers/jira_sessions_controller.rb class JiraSessionsController < ApplicationController before_filter :get_jira_client def new request_token = @jira_client.request_token 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.
# 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
Here’s the same example as a Sinatra application:
require 'jira' 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 request_token = @jira_client.request_token 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