jira-ruby: a Ruby gem for talking to the JIRA REST API

A thin wrapper over the REST API, in the Ruby idiom

jira-ruby is a gem that provides access to the Atlassian JIRA REST API. The repository is small in the way a good API wrapper should be: a lib/ directory, a spec/ directory, a Gemfile, a Rakefile, a gemspec and a .rubocop.yml for style, plus a .yardopts file for documentation generation.

The value is not in new abstractions. It is in turning REST payloads into Ruby objects you can call methods on, and in handling the authentication dance that a JIRA instance imposes. The README points at the official Atlassian overview and reference documentation for the underlying API, which tells you the gem is a convenience layer over a documented service rather than a separate abstraction of its own.

Installing it is a standard gem install:

gem install jira-ruby

The audience is Ruby developers who need to talk to JIRA from a script, a bot, a rake task or a service. If you are writing a one-off report that needs issues filtered by JQL, or a bot that opens a ticket when a build breaks, this is the tool for that job, and it is MIT licensed so it fits inside a proprietary codebase without friction.

Four authentication paths, chosen by one option key

Authentication is where JIRA clients usually get complicated, and the gem exposes the choice through the options hash you pass to JIRA::Client.new.

The OAuth path expects an RSA private key file, a consumer key and the site URL:

options = {
  :private_key_file => "rsakey.pem",
  :context_path     => '',
  :consumer_key     => 'your_consumer_key',
  :site             => 'your_jira_instance_url'
}

client = JIRA::Client.new(options)

The README also lists Personal Access Token among the other supported ways to connect, and documents two more. HTTP basic authentication needs no incoming authentication configuration, because that is the default for an Application Link. Cookie based authentication passes credentials to JIRA in a REST call, receives a session cookie, and sends it on every subsequent request:

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)

The :additional_cookies option exists for schemes that need extra cookies on each request, and it takes an array of cookie strings.

One constraint is stated plainly. Two-legged OAuth in server mode only, not in cloud based JIRA, and the README tells you to make sure Allow 2-Legged OAuth is enabled. If you point this gem at a JIRA Cloud instance, that path is closed to you.

Field mapping is what makes customfield identifiers usable

A recurring annoyance in JIRA scripting is the customfield_12345 identifier. The gem lets you refer to fields by their custom names once you map them, and the mapping is a single call on the client:

client.Field.map_fields

old_way = issue.customfield_12345

# Note: The methods mapped here adopt a unique style combining PascalCase and snake_case conventions.
new_way = issue.Special_Field

The comment in the sample says it plainly: the mapped methods adopt a style that combines PascalCase and snake_case conventions, so Special_Field is the accessor name. The README is explicit that you must map the fields before using them, which is a real detail, because an unmapped field will not have a method to call.

Once mapping is done, the same field name works everywhere the API takes a field list, which includes JQL queries. The query example passes a field list that mixes standard fields with the mapped custom one:

client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :Special_field, :created])

That combination, one call to map fields and then the same names in the field list, is the reason the mapping call is worth doing once at start-up rather than sprinkling identifiers through your code.

Build, save, transition, delete: the issue lifecycle in four calls

The issue object carries the write operations, and the README shows each of them.

Creating an issue starts with a build call and a save with a fields hash:

issue = client.Issue.build
labels = ['label1', 'label2']
issue.save({
  "fields" => {
    "summary" => "blarg from in example.rb",
    "project" => {"key" => "SAMPLEPROJECT"},
    "issuetype" => {"id" => "3"},
    "labels" => labels,
    "priority" => {"id" => "1"}
  }
})

Updating and transitioning are two different calls, and the transition needs its own build step:

issue = client.Issue.find("10002")
issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA!"}})

issue_transition = issue.transitions.build
issue_transition.save!('transition' => {'id' => transition_id})

Deleting is a method on the issue, and you need the issue key or id:

issue = client.Issue.find('SAMPLEPROJECT-2')
issue.delete

Reading projects follows the same shape, since a client exposes resource collections that answer to all:

projects = client.Project.all

projects.each do |project|
  puts "Project -> key: #{project.key}, name: #{project.name}"
end

The README also lists other capabilities beyond these: searching for a user, retrieving an issue's watchers, changing the assignee, adding attachments and comments, and managing issue links. It points to a complete script example in the repository for the full set.

The test suite expects a local JIRA and a generated certificate

Running the tests is the part of this project that asks the most from a contributor, and the README is explicit about the prerequisites.

First you need a public certificate, generated with a rake task:

rake jira:generate_public_cert

Second you need a JIRA to talk to. The README describes setting up the Atlassian SDK on Mac OS and then running the standalone product from within the archive directory:

./bin/atlas-run-standalone --product jira

Once that is running, the README says you should be able to connect to http://localhost:2990/ and log in to the JIRA admin system using admin:admin. It also tells you to create a dummy project and probably some issues to test with the library.

That is a heavier test setup than most gems ask for, and it is the practical cost of this project. The integration tests need a real JIRA instance, so contributing or running the suite locally means standing up a server, not spinning up a mock. A CI badge for the test workflow exists, which suggests the project runs this setup on its own infrastructure, and there is a CodeQL workflow alongside it.

If your team only needs the library, none of this is required. It only matters if you intend to change the gem or run its suite.

Release history, dual editions and the shape of the gem

The repository has a steady release record. v3.2.0 is dated 2026-05-20, v3.2.1 on 2026-07-24, and v3.2.2 on 2026-08-19, with the last push to the repository on the same day as v3.2.2. That is a project with regular tagged versions rather than a continuously moving branch, which matters if you pin the gem in a Gemfile.

The licence is MIT, with a LICENSE file at the root of the repository. A wrapper like this is the kind of dependency most teams can vendor without legal review, since it adds no copyleft obligation.

The project structure shows the usual Ruby conventions. The gemspec is jira-ruby.gemspec, the library code sits in lib/, and the tests in spec/. A Guardfile is present, which is the file-watch tool used during test-driven development, and the .yardopts file configures the YARD documentation generator that the gemspec and repository reference.

The README ends by pointing at the Atlassian documentation rather than duplicating it, with links to the REST API overview and the REST reference. For a wrapper whose job is to stay current with a vendor API, that arrangement is reasonable, and it also means the gem is not trying to be a second source of truth about JIRA's endpoints.

Editorial conclusion

jira-ruby suits Ruby teams that need a scriptable handle on a JIRA instance, whether that is a one-off report, a bot that opens tickets, or an integration that reads issues through JQL. It does not suit a project that needs the platform APIs or a heavier client framework, and it does not suit a cloud JIRA that relies on two-legged OAuth, because the README states that mode is for server mode only. Check three things before you build on it: which auth type your instance accepts, whether the fields you need exist as mappable names or only as customfield identifiers, and whether you can run a local JIRA for the test suite, since rake jira:generate_public_cert and the standalone server are part of the documented test path. The last push to the repository was on 2026-08-19 and the newest release is v3.2.2 from the same date.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sumoheavy/jira-ruby on GitHub