jira-ruby 2.3.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 113ad755633d6eb87e63d7a97d3228f6649828547c01dee1ae1900ef0d575e2d
-  data.tar.gz: d59620f52976814ee7db58df10213bdb512f042a8b8214789ed07288f2899b65
+  metadata.gz: 4a043cafa57aad32acfda37495a8419b4511581786620049cb6264a05265aefb
+  data.tar.gz: 2c3b66dd69faaef351e043b10c62f3cfd7662e003905363db6bdbf458bfb10b1
 SHA512:
-  metadata.gz: e523698732b5cef8a220259ccf5c42c568ac7eea435ee2ed2f2018cdd25959597d23337a67fac037e00be85a8838d9d32a2c79a156da008380699d2c9529cb03
-  data.tar.gz: cefe63455cb070951d73420dc1144b0c0a4651836427f507d218d3eb0780936e6a740842f6f2df8f68b14be8034bb196b4f5069d21ac0c3cd9e2a4292e43b456
+  metadata.gz: 677a496c74235ea213ac92416b9dfb303e56bc04ea94b617134925ce744c25bd81583b2516a342c347a935959795c35813245499efcf2c058b075d308ef51454
+  data.tar.gz: ef42dd385a24ff73526e8e2d21fedb0af60832444f9d1e43c0c23a1cca58da61751a24901430abf0650cffacdd7b41ff28fa7620deb195ede7081af504eb4295

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: Bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+A runnable code example to reproduce the issue.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: Feature
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context about the feature request here.

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/CI.yml

@@ -0,0 +1,30 @@
+name: Ruby
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: CI-tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '4.0'
+          - '3.4'
+          - '3.3'
+          - '3.2'
+          - '3.1'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: |
+          bundle exec rake jira:generate_public_cert
+          bundle exec rake spec

data/.github/workflows/codeql.yml

@@ -0,0 +1,96 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "master" ]
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    branches: [ "master" ]
+    paths-ignore:
+      - '**/*.md'
+  schedule:
+    - cron: '0 13 * * *'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: ruby
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - if: matrix.build-mode == 'manual'
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

data/.github/workflows/rubocop.yml

@@ -0,0 +1,18 @@
+name: Rubocop
+
+on: [push, pull_request]
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - name: Run rubocop
+        run: |
+          bundle exec rubocop --format github

data/.gitignore

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

data/.rubocop.yml

@@ -0,0 +1,123 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  Exclude:
+    - 'vendor/**/*'
+  NewCops: enable
+  TargetRubyVersion: 3.1
+
+Naming/FileName:
+  Exclude:
+    - 'lib/jira-ruby.rb'
+
+Naming/MethodName:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - 'spec/**/*'
+
+##
+# Temporarily Disable
+# 
+# We are going to disable these and fix in pull requests
+##
+Layout/LineLength:
+  Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Lint/EmptyClass:
+  Enabled: false
+
+Lint/IneffectiveAccessModifier:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/HeredocDelimiterNaming:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Naming/PredicateMethod:
+  AllowBangMethods: true
+
+Naming/VariableNumber:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/ExpectInHook:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/LeakyConstantDeclaration:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NamedSubject:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/ReceiveMessages:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+RSpec/SubjectStub:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+Style/MissingRespondToMissing:
+  Enabled: false
+
+Style/OptionalBooleanParameter:
+  Enabled: false

data/.yardopts

@@ -0,0 +1,4 @@
+--title "Jira Ruby"
+--no-private
+lib/**/*.rb
+

data/Gemfile

@@ -1,13 +1,21 @@
-source 'http://rubygems.org'
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 group :development do
-  gem 'guard'
-  gem 'guard-rspec'
+  gem 'guard', '~> 2.18', '>= 2.18.1'
+  gem 'guard-rspec', '~> 4.7', '>= 4.7.3'
+  gem 'railties'
+  gem 'rake', '~> 13.2', '>= 13.2.1'
+  gem 'rspec', '~> 3.0', '>= 3.13'
   gem 'wdm', '>= 0.1.0' if Gem.win_platform?
+  gem 'webmock', '~> 3.23', '>= 3.23.0'
 end
 
 group :development, :test do
   gem 'pry' # this was in the original Gemfile - but only needed in development & test
+  gem 'rubocop'
+  gem 'rubocop-rspec', require: false
 end
 
 # Specify your gem's dependencies in jira_api.gemspec

data/Guardfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 gem 'wdm', '>= 0.1.0' if Gem.win_platform?
 gem 'rspec', '~> 3.0.0'
 

data/README.md

@@ -1,37 +1,113 @@
 # 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)
+[![Build Status](https://github.com/sumoheavy/jira-ruby/actions/workflows/CI.yml/badge.svg)](https://github.com/sumoheavy/jira-ruby/actions/workflows/CI.yml)
 
 This gem provides access to the Atlassian JIRA REST API.
 
-## Slack
+## Example usage
 
-Join our Slack channel! You can find us [here](https://jira-ruby-slackin.herokuapp.com/)
+# Jira Ruby API - Sample Usage
 
-## Example usage
+This sample usage demonstrates how you can interact with JIRA's API using the [jira-ruby gem](https://github.com/sumoheavy/jira-ruby).
 
-```ruby
-require 'rubygems'
-require 'jira-ruby'
+### Dependencies
+
+Before running, install the `jira-ruby` gem:
 
+```shell
+gem install jira-ruby
+```
+
+### Sample Usage
+Connect to JIRA
+Firstly, establish a connection with your JIRA instance by providing a few configuration parameters:
+There are other ways to connect to JIRA listed below |  [Personal Access Token](#configuring-jira-to-use-personal-access-tokens-auth)
+- private_key_file: The path to your RSA private key file.
+- consumer_key: Your consumer key.
+- site: The URL of your JIRA instance.
+
+```ruby
 options = {
-  :username     => 'username',
-  :password     => 'pass1234',
-  :site         => 'http://mydomain.atlassian.net:443/',
-  :context_path => '',
-  :auth_type    => :basic
+  :private_key_file => "rsakey.pem",
+  :context_path     => '',
+  :consumer_key     => 'your_consumer_key',
+  :site             => 'your_jira_instance_url'
 }
 
 client = JIRA::Client.new(options)
+```
 
-project = client.Project.find('SAMPLEPROJECT')
+### Retrieve and Display Projects
 
-project.issues.each do |issue|
-  puts "#{issue.id} - #{issue.summary}"
+After establishing the connection, you can fetch all projects and display their key and name:
+```ruby
+projects = client.Project.all
+
+projects.each do |project|
+  puts "Project -> key: #{project.key}, name: #{project.name}"
 end
 ```
 
+### Handling Fields by Name
+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:
+
+```ruby
+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
+```
+
+### JQL Queries
+To find issues based on specific criteria, you can use JIRA Query Language (JQL):
+
+```ruby
+client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :Special_field, :created])
+```
+
+### Several actions can be performed on the Issue object such as create, update, transition, delete, etc:
+### Creating an Issue
+```ruby
+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/Transitioning an Issue
+```ruby
+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 an Issue
+```ruby
+issue = client.Issue.find('SAMPLEPROJECT-2')
+issue.delete
+```
+
+### Other Capabilities
+Apart from the operations listed above, this API wrapper supports several other capabilities like:
+	•	Searching for a user
+	•	Retrieving an issue's watchers
+	•	Changing the assignee of an issue
+	•	Adding attachments and comments to issues
+	•	Managing issue links and much more.
+
+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.
+
 ## Links to JIRA REST API documentation
 
 * [Overview](https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs)
@@ -87,7 +163,7 @@ 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`
+For two 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
 
@@ -148,8 +224,7 @@ 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,
+  :default_headers    => { 'Authorization' => "Bearer #{api_token}" },
   :auth_type          => :basic
 }
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 
 require 'rubygems'
@@ -13,13 +15,10 @@ task test: %i[prepare spec]
 desc 'Prepare and run rspec tests'
 task :prepare do
   rsa_key = File.expand_path('rsakey.pem')
-  unless File.exist?(rsa_key)
-    Rake::Task['jira:generate_public_cert'].invoke
-  end
+  Rake::Task['jira:generate_public_cert'].invoke unless File.exist?(rsa_key)
 end
 
 desc 'Run RSpec tests'
-# RSpec::Core::RakeTask.new(:spec)
 RSpec::Core::RakeTask.new(:spec, [] => [:prepare]) do |task|
   task.rspec_opts = ['--color', '--format', 'doc']
 end

data/jira-ruby.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 $LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'jira/version'
 
@@ -9,27 +11,20 @@ Gem::Specification.new do |s|
   s.summary     = 'Ruby Gem for use with the Atlassian JIRA REST API'
   s.description = 'API for JIRA'
   s.licenses    = ['MIT']
-  s.metadata    = { 'source_code_uri' => 'https://github.com/sumoheavy/jira-ruby' }
+  s.metadata    = {
+    'source_code_uri' => 'https://github.com/sumoheavy/jira-ruby',
+    'rubygems_mfa_required' => 'true'
+  }
 
-  s.required_ruby_version = '>= 1.9.3'
+  s.required_ruby_version = '>= 3.1.0'
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  # Runtime Dependencies
-  s.add_runtime_dependency 'activesupport'
-  s.add_runtime_dependency 'atlassian-jwt'
-  s.add_runtime_dependency 'multipart-post'
-  s.add_runtime_dependency 'oauth', '~> 0.5', '>= 0.5.0'
-
-  # Development Dependencies
-  s.add_development_dependency 'guard', '~> 2.13', '>= 2.13.0'
-  s.add_development_dependency 'guard-rspec', '~> 4.6', '>= 4.6.5'
-  s.add_development_dependency 'pry', '~> 0.10', '>= 0.10.3'
-  s.add_development_dependency 'railties'
-  s.add_development_dependency 'rake', '~> 10.3', '>= 10.3.2'
-  s.add_development_dependency 'rspec', '~> 3.0', '>= 3.0.0'
-  s.add_development_dependency 'webmock', '~> 1.18', '>= 1.18.0'
+  s.add_dependency 'activesupport'
+  s.add_dependency 'cgi'
+  s.add_dependency 'jwt', '>= 2.1'
+  s.add_dependency 'multipart-post'
+  s.add_dependency 'oauth', '~> 1.0'
 end

data/lib/jira/atlassian/jwt.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Copyright 2013 Atlassian Pty Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'jwt'
+require 'uri'
+require 'cgi'
+
+module JIRA
+  module Atlassian
+    module Jwt
+      class << self
+        CANONICAL_QUERY_SEPARATOR = '&'
+        ESCAPED_CANONICAL_QUERY_SEPARATOR = '%26'
+
+        def create_canonical_request(uri, http_method, base_uri)
+          uri = URI.parse(uri) unless uri.is_a? URI
+          base_uri = URI.parse(base_uri) unless base_uri.is_a? URI
+
+          [
+            http_method.upcase,
+            canonicalize_uri(uri, base_uri),
+            canonicalize_query_string(uri.query)
+          ].join(CANONICAL_QUERY_SEPARATOR)
+        end
+
+        def build_claims(issuer, url, http_method, base_url = '', issued_at = nil, expires = nil, attributes = {}) # rubocop:disable Metrics/ParameterLists
+          issued_at ||= Time.now.to_i
+          expires ||= issued_at + 60
+          qsh = Digest::SHA256.hexdigest(create_canonical_request(url, http_method, base_url))
+
+          {
+            iss: issuer,
+            iat: issued_at,
+            exp: expires,
+            qsh: qsh
+          }.merge(attributes)
+        end
+
+        def canonicalize_uri(uri, base_uri)
+          path = uri.path.sub(/^#{base_uri.path}/, '')
+          path = '/' if path.nil? || path.empty?
+          path = "/#{path}" unless path.start_with? '/'
+          path.chomp!('/') if path.length > 1
+          path.gsub(CANONICAL_QUERY_SEPARATOR, ESCAPED_CANONICAL_QUERY_SEPARATOR)
+        end
+
+        def canonicalize_query_string(query)
+          return '' if query.nil? || query.empty?
+
+          query = CGI.parse(query)
+          query.delete('jwt')
+          query.each do |k, v|
+            query[k] = v.map { |a| CGI.escape a }.join(',') if v.is_a? Array
+            query[k].gsub!('+', '%20')  # Use %20, not CGI.escape default of "+"
+            query[k].gsub!('%7E', '~')  # Unescape "~" per JS tests
+          end
+          query = query.sort.to_h
+          query.map { |k, v| "#{CGI.escape k}=#{v}" }.join(CANONICAL_QUERY_SEPARATOR)
+        end
+      end
+    end
+  end
+end