https://github.com/gbevan/jira-ruby-glb

API for JIRA
https://github.com/gbevan/jira-ruby-glb

Last synced: 10 months ago
JSON representation

API for JIRA

• Host: GitHub
• URL: https://github.com/gbevan/jira-ruby-glb
• Owner: gbevan
• License: osl-3.0
• Created: 2014-10-11T11:52:54.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2014-10-11T16:42:06.000Z (over 11 years ago)
• Last Synced: 2025-03-14T02:29:19.391Z (over 1 year ago)
• Language: Ruby
• Size: 188 KB
• Stars: 0
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.rdoc
  • License: LICENSE.txt

Awesome Lists containing this project

README

          
= JIRA API Gem

{}[https://codeclimate.com/github/sumoheavy/jira-ruby]

{ 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

== Links to JIRA REST API documentation

* {Overview}[https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs]

* {Reference}[http://docs.atlassian.com/jira/REST/latest/]

== Setting up the JIRA SDK

On Mac OS,

* Follow the instructions under "Mac OSX Installer" here: https://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

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.

== 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.

== Using the API Gem in a command line application

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 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

  # 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

== Using the API Gem in your Sinatra application

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:///

    # 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

          
jira-ruby (JIRA 5 Ruby Gem) demo 
You're not signed in. Why don't you 

          sign in 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. Signout

        eos

      end

    end

    # http:///signin

    # Initiates the OAuth dance by first requesting a token then redirecting to 

    # http:///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:///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:///signout

    # Expires the session

    get "/signout" do

      session.delete(:jira_auth)

      redirect "/"

    end

  end