Skip to content

Commit 69c41de

Browse files
bobbrodiebobbrodie
authored
Merge branch 'master' into max_retries
2 parents 4404aaf + af3f3a4 commit 69c41de

35 files changed

+652
-236
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve
4+
title: ''
5+
labels: Bug
6+
assignees: ''
7+
8+
---
9+
10+
**Describe the bug**
11+
A clear and concise description of what the bug is.
12+
13+
**To Reproduce**
14+
A runnable code example to reproduce the issue.
15+
16+
**Expected behavior**
17+
A clear and concise description of what you expected to happen.
18+
19+
**Additional context**
20+
Add any other context about the problem here.

‎.github/ISSUE_TEMPLATE/feature_request.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
name: Feature request
3+
about: Suggest an idea for this project
4+
title: ''
5+
labels: Feature
6+
assignees: ''
7+
8+
---
9+
10+
**Is your feature request related to a problem? Please describe.**
11+
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12+
13+
**Describe the solution you'd like**
14+
A clear and concise description of what you want to happen.
15+
16+
**Describe alternatives you've considered**
17+
A clear and concise description of any alternative solutions or features you've considered.
18+
19+
**Additional context**
20+
Add any other context about the feature request here.

‎.github/workflows/CI.yml

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Ruby
2+
3+
on: [push, pull_request]
4+
5+
jobs:
6+
test:
7+
name: CI-tests
8+
runs-on: ubuntu-latest
9+
strategy:
10+
fail-fast: false
11+
matrix:
12+
ruby:
13+
- '3.3'
14+
- '3.2'
15+
- '3.1'
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Setup Ruby
20+
uses: ruby/setup-ruby@v1
21+
with:
22+
ruby-version: ${{ matrix.ruby }}
23+
bundler-cache: true
24+
25+
- name: Run tests
26+
run: |
27+
bundle exec rake jira:generate_public_cert
28+
bundle exec rake spec

‎.travis.yml

-9
This file was deleted.

‎Gemfile

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
source 'http://rubygems.org'
1+
source 'https://rubygems.org'
22

33
group :development do
44
gem 'guard'

‎README.md

+93-16
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,114 @@
11
# JIRA API Gem
22

33
[![Code Climate](https://codeclimate.com/github/sumoheavy/jira-ruby.svg)](https://codeclimate.com/github/sumoheavy/jira-ruby)
4-
[![Build Status](https://travis-ci.org/sumoheavy/jira-ruby.svg?branch=master)](https://travis-ci.org/sumoheavy/jira-ruby)
4+
[![Build Status](https://github.com/sumoheavy/jira-ruby/actions/workflows/CI.yml/badge.svg)](https://github.com/sumoheavy/jira-ruby/actions/workflows/CI.yml)
55

66
This gem provides access to the Atlassian JIRA REST API.
77

8-
## Slack
8+
## Example usage
99

10-
Join our Slack channel! You can find us [here](https://jira-ruby-slackin.herokuapp.com/)
10+
# Jira Ruby API - Sample Usage
1111

12-
## Example usage
12+
This sample usage demonstrates how you can interact with JIRA's API using the [jira-ruby gem](https://github.com/sumoheavy/jira-ruby).
1313

14-
```ruby
15-
require 'rubygems'
16-
require 'jira-ruby'
14+
### Dependencies
15+
16+
Before running, install the `jira-ruby` gem:
1717

18+
```shell
19+
gem install jira-ruby
20+
```
21+
22+
### Sample Usage
23+
Connect to JIRA
24+
Firstly, establish a connection with your JIRA instance by providing a few configuration parameters:
25+
There are other ways to connect to JIRA listed below | [Personal Access Token](#configuring-jira-to-use-personal-access-tokens-auth)
26+
- private_key_file: The path to your RSA private key file.
27+
- consumer_key: Your consumer key.
28+
- site: The URL of your JIRA instance.
29+
30+
```ruby
1831
options = {
19-
:username => 'username',
20-
:password => 'pass1234',
21-
:site => 'http://mydomain.atlassian.net:443/',
22-
:context_path => '',
23-
:auth_type => :basic
32+
:private_key_file => "rsakey.pem",
33+
:context_path => '',
34+
:consumer_key => 'your_consumer_key',
35+
:site => 'your_jira_instance_url'
2436
}
2537

2638
client = JIRA::Client.new(options)
39+
```
2740

28-
project = client.Project.find('SAMPLEPROJECT')
41+
### Retrieve and Display Projects
2942

30-
project.issues.each do |issue|
31-
puts "#{issue.id} - #{issue.summary}"
43+
After establishing the connection, you can fetch all projects and display their key and name:
44+
```ruby
45+
projects = client.Project.all
46+
47+
projects.each do |project|
48+
puts "Project -> key: #{project.key}, name: #{project.name}"
3249
end
3350
```
3451

52+
### Handling Fields by Name
53+
The jira-ruby gem allows you to refer to fields by their custom names rather than identifiers. Make sure to map fields before using them:
54+
55+
```ruby
56+
client.Field.map_fields
57+
58+
old_way = issue.customfield_12345
59+
60+
# Note: The methods mapped here adopt a unique style combining PascalCase and snake_case conventions.
61+
new_way = issue.Special_Field
62+
```
63+
64+
### JQL Queries
65+
To find issues based on specific criteria, you can use JIRA Query Language (JQL):
66+
67+
```ruby
68+
client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :Special_field, :created])
69+
```
70+
71+
### Several actions can be performed on the Issue object such as create, update, transition, delete, etc:
72+
### Creating an Issue
73+
```ruby
74+
issue = client.Issue.build
75+
labels = ['label1', 'label2']
76+
issue.save({
77+
"fields" => {
78+
"summary" => "blarg from in example.rb",
79+
"project" => {"key" => "SAMPLEPROJECT"},
80+
"issuetype" => {"id" => "3"},
81+
"labels" => labels,
82+
"priority" => {"id" => "1"}
83+
}
84+
})
85+
```
86+
87+
### Updating/Transitioning an Issue
88+
```ruby
89+
issue = client.Issue.find("10002")
90+
issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA!"}})
91+
92+
issue_transition = issue.transitions.build
93+
issue_transition.save!('transition' => {'id' => transition_id})
94+
```
95+
96+
### Deleting an Issue
97+
```ruby
98+
issue = client.Issue.find('SAMPLEPROJECT-2')
99+
issue.delete
100+
```
101+
102+
### Other Capabilities
103+
Apart from the operations listed above, this API wrapper supports several other capabilities like:
104+
• Searching for a user
105+
• Retrieving an issue's watchers
106+
• Changing the assignee of an issue
107+
• Adding attachments and comments to issues
108+
• Managing issue links and much more.
109+
110+
Not all examples are shown in this README; refer to the complete script example for a full overview of the capabilities supported by this API wrapper.
111+
35112
## Links to JIRA REST API documentation
36113

37114
* [Overview](https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs)
@@ -87,7 +164,7 @@ key.
87164
> After you have entered all the information click OK and ensure OAuth authentication is
88165
> enabled.
89166
90-
For 2 legged oauth in server mode only, not in cloud based JIRA, make sure to `Allow 2-Legged OAuth`
167+
For two legged oauth in server mode only, not in cloud based JIRA, make sure to `Allow 2-Legged OAuth`
91168

92169
## Configuring JIRA to use HTTP Basic Auth
93170

‎jira-ruby.gemspec

+8-8
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
1111
s.licenses = ['MIT']
1212
s.metadata = { 'source_code_uri' => 'https://github.com/sumoheavy/jira-ruby' }
1313

14-
s.required_ruby_version = '>= 1.9.3'
14+
s.required_ruby_version = '>= 3.1.0'
1515

1616
s.files = `git ls-files`.split("\n")
1717
s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
@@ -22,14 +22,14 @@ Gem::Specification.new do |s|
2222
s.add_runtime_dependency 'activesupport'
2323
s.add_runtime_dependency 'atlassian-jwt'
2424
s.add_runtime_dependency 'multipart-post'
25-
s.add_runtime_dependency 'oauth', '~> 0.5', '>= 0.5.0'
25+
s.add_runtime_dependency 'oauth', '~> 1.0'
2626

2727
# Development Dependencies
28-
s.add_development_dependency 'guard', '~> 2.13', '>= 2.13.0'
29-
s.add_development_dependency 'guard-rspec', '~> 4.6', '>= 4.6.5'
30-
s.add_development_dependency 'pry', '~> 0.10', '>= 0.10.3'
28+
s.add_development_dependency 'guard', '~> 2.18', '>= 2.18.1'
29+
s.add_development_dependency 'guard-rspec', '~> 4.7', '>= 4.7.3'
30+
s.add_development_dependency 'pry', '~> 0.14', '>= 0.14.3'
3131
s.add_development_dependency 'railties'
32-
s.add_development_dependency 'rake', '~> 10.3', '>= 10.3.2'
33-
s.add_development_dependency 'rspec', '~> 3.0', '>= 3.0.0'
34-
s.add_development_dependency 'webmock', '~> 1.18', '>= 1.18.0'
32+
s.add_development_dependency 'rake', '~> 13.2', '>= 13.2.1'
33+
s.add_development_dependency 'rspec', '~> 3.0', '>= 3.13'
34+
s.add_development_dependency 'webmock', '~> 3.23', '>= 3.23.0'
3535
end

‎lib/jira-ruby.rb

+2-1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
require 'jira/resource/issuetype'
1919
require 'jira/resource/version'
2020
require 'jira/resource/status'
21+
require 'jira/resource/status_category'
2122
require 'jira/resource/transition'
2223
require 'jira/resource/project'
2324
require 'jira/resource/priority'
@@ -32,11 +33,11 @@
3233
require 'jira/resource/remotelink'
3334
require 'jira/resource/sprint'
3435
require 'jira/resource/sprint_report'
36+
require 'jira/resource/resolution'
3537
require 'jira/resource/issue'
3638
require 'jira/resource/filter'
3739
require 'jira/resource/field'
3840
require 'jira/resource/rapidview'
39-
require 'jira/resource/resolution'
4041
require 'jira/resource/serverinfo'
4142
require 'jira/resource/createmeta'
4243
require 'jira/resource/webhook'

‎lib/jira/base.rb

+1-1
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ def self.collection_path(client, prefix = '/')
141141
# JIRA::Resource::Comment.singular_path('456','/issue/123/')
142142
# # => /jira/rest/api/2/issue/123/comment/456
143143
def self.singular_path(client, key, prefix = '/')
144-
collection_path(client, prefix) + '/' + key
144+
collection_path(client, prefix) + '/' + key.to_s
145145
end
146146

147147
# Returns the attribute name of the attribute used for find.

‎lib/jira/client.rb

+5-1
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,10 @@ def Status # :nodoc:
184184
JIRA::Resource::StatusFactory.new(self)
185185
end
186186

187+
def StatusCategory # :nodoc:
188+
JIRA::Resource::StatusCategoryFactory.new(self)
189+
end
190+
187191
def Resolution # :nodoc:
188192
JIRA::Resource::ResolutionFactory.new(self)
189193
end
@@ -293,7 +297,7 @@ def post(path, body = '', headers = {})
293297

294298
def post_multipart(path, file, headers = {})
295299
puts "post multipart: #{path} - [#{file}]" if @http_debug
296-
@request_client.request_multipart(path, file, headers)
300+
@request_client.request_multipart(path, file, merge_default_headers(headers))
297301
end
298302

299303
def put(path, body = '', headers = {})

‎lib/jira/http_client.rb

+6-6
Original file line numberDiff line numberDiff line change
@@ -45,12 +45,12 @@ def basic_auth_http_conn
4545
end
4646

4747
def http_conn(uri)
48-
if @options[:proxy_address]
49-
http_class = Net::HTTP::Proxy(@options[:proxy_address], @options[:proxy_port] || 80, @options[:proxy_username], @options[:proxy_password])
50-
else
51-
http_class = Net::HTTP
52-
end
53-
http_conn = http_class.new(uri.host, uri.port)
48+
http_conn =
49+
if @options[:proxy_address]
50+
Net::HTTP.new(uri.host, uri.port, @options[:proxy_address], @options[:proxy_port] || 80, @options[:proxy_username], @options[:proxy_password])
51+
else
52+
Net::HTTP.new(uri.host, uri.port)
53+
end
5454
http_conn.use_ssl = @options[:use_ssl]
5555
if @options[:use_client_cert]
5656
http_conn.cert = @options[:ssl_client_cert]

‎lib/jira/http_error.rb

+2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
require 'forwardable'
2+
require 'active_support/core_ext/object'
3+
24
module JIRA
35
class HTTPError < StandardError
46
extend Forwardable

0 commit comments

Comments
 (0)