issue-db 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7e786c1b79b72e6ef52d8347d5d647f5275c714fd72699fd187032034ee0aae
-  data.tar.gz: 6f18ea1176291ab1a6da20e90bc7e95d7ca3f727097c012a31bf3adb50faf1e3
+  metadata.gz: 740a1a64de7f9ab45fd7932682999972139392b4c8d8f48105cde4f49e9474b1
+  data.tar.gz: 6219653cb7f2303482e039f906ae788e4d9f9a89131df12e750ef35cc0f8a976
 SHA512:
-  metadata.gz: 4379608b58b9cc396deeabfed41e01753e927792483000f3047e4c600eb0b2cf02e49ee53c3b8c34a7de494713899f9abc944013d344263961a20e13197a2cab
-  data.tar.gz: 11da329ed7e764483a38934d552ad87dddbec88b9be0136de249fa45d5519604b176b9a3fe2f33d5a13c61e37c64c1af374fc2e8cdbe774e45065bae28cf8d89
+  metadata.gz: 743c37f2ca18320e7ce68f4c5f88b2275a19c93f2239d10c7a1b5102ffb089444fb79ca947efef6dd47792bfeeafe82ead49812e92605f2ccafa0b351ce9ac43
+  data.tar.gz: cb0eb761ee2dfa89c3fc0f8d096957269905052778756a09fc755c3a5975264c690e725e38f707e4a10be618e8255f6b2cde26d1755d4ddac3d06c919e7499b7

data/README.md

@@ -65,9 +65,12 @@ gem install issue-db --version "X.X.X"
 
 ## Usage 💻
 
-The following CRUD operations are available for the `issue-db` gem:
+This section goes into details on the following CRUD operations are available for the `issue-db` gem.
 
-> Note: All methods return the `IssueDB::Record` of the object which was involved in the operation
+Note: All methods return the `IssueDB::Record` of the object which was involved in the operation
+
+> [!IMPORTANT]  
+> The key for the record is the title of the GitHub issue. This means that the key **must be unique** within the database. If you try to do any sort of duplicate operation on a key that already exists (like creating it again), the `issue-db` gem will return the existing record without modifying it. Here is an example log message where someone calls `db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] })` but the key already exists: `skipping issue creation and returning existing issue - an issue already exists with the key: order_number_123`. Additionally, if there are duplicates (same issue titles), then the latest issue will be returned (ex: issue 15 will be returned instead of issue 14). Basically, if you use fully unique keys, you won't ever run into this issue so please make sure to use unique keys for your records!
 
 ### `db.create(key, data, options = {})`
 
@@ -194,13 +197,14 @@ This section will go into detail around how you can configure the `issue-db` gem
 
 ## Authentication 🔒
 
-The `issue-db` gem uses the [`Octokit.rb`](https://github.com/octokit/octokit.rb) library under the hood for interactions with the GitHub API. You have three options for authentication when using the `issue-db` gem:
+The `issue-db` gem uses the [`Octokit.rb`](https://github.com/octokit/octokit.rb) library under the hood for interactions with the GitHub API. You have four options for authentication when using the `issue-db` gem:
 
 > Note: The order displayed below is also the order of priority that this Gem uses to authenticate.
 
 1. Pass in your own authenticated `Octokit.rb` instance to the `IssueDB.new` method
-2. Use a GitHub App by setting the `ISSUE_DB_GITHUB_APP_ID`, `ISSUE_DB_GITHUB_APP_INSTALLATION_ID`, and `ISSUE_DB_GITHUB_APP_KEY` environment variables
-3. Use a GitHub personal access token by setting the `ISSUE_DB_GITHUB_TOKEN` environment variable
+2. Pass GitHub App authentication parameters directly to the `IssueDB.new` method
+3. Use a GitHub App by setting the `ISSUE_DB_GITHUB_APP_ID`, `ISSUE_DB_GITHUB_APP_INSTALLATION_ID`, and `ISSUE_DB_GITHUB_APP_KEY` environment variables
+4. Use a GitHub personal access token by setting the `ISSUE_DB_GITHUB_TOKEN` environment variable
 
 > Using a GitHub App is the suggested method
 
@@ -215,7 +219,31 @@ require "issue_db"
 db = IssueDB.new("<org>/<repo>") # THAT'S IT! 🎉
 ```
 
-### Using a GitHub App
+### Using GitHub App Parameters Directly
+
+You can now pass GitHub App authentication parameters directly to the `IssueDB.new` method. This is especially useful when you want to manage authentication credentials in your application code or when you have multiple GitHub Apps for different purposes:
+
+```ruby
+require "issue_db"
+
+# Pass GitHub App credentials directly to IssueDB.new
+db = IssueDB.new(
+  "<org>/<repo>",
+  app_id: 12345,                    # Your GitHub App ID
+  installation_id: 56789,          # Your GitHub App Installation ID
+  app_key: "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",  # Your GitHub App private key
+  app_algo: "RS256"                 # Optional: defaults to RS256
+)
+```
+
+**Parameters:**
+
+- `app_id` (Integer) - Your GitHub App ID (found on the App's settings page)
+- `installation_id` (Integer) - Your GitHub App Installation ID (found in the installation URL: `https://github.com/organizations/<org>/settings/installations/<installation_id>`)
+- `app_key` (String) - Your GitHub App private key (can be the key content as a string or a file path ending in `.pem`)
+- `app_algo` (String, optional) - The algorithm to use for JWT signing (defaults to "RS256")
+
+### Using a GitHub App with Environment Variables
 
 This is the single best way to use the `issue-db` gem because GitHub Apps have increased rate limits, fine-grained permissions, and are more secure than using a personal access token. All you have to do is provide three environment variables and the `issue-db` gem will take care of the rest:
 

data/issue-db.gemspec

@@ -4,7 +4,7 @@ require_relative "lib/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "issue-db"
-  spec.version       = Version::VERSION
+  spec.version       = IssueDB::Version::VERSION
   spec.authors       = ["runwaylab", "GrantBirki"]
   spec.license       = "MIT"
 

data/lib/issue_db/authentication.rb

@@ -3,37 +3,45 @@
 require "octokit"
 require_relative "utils/github"
 
-class AuthenticationError < StandardError; end
+module IssueDB
+  class AuthenticationError < StandardError; end
 
-module Authentication
-  def self.login(client = nil, log = nil)
-    # if the client is not nil, use the pre-provided client
-    unless client.nil?
-      log.debug("using pre-provided client") if log
-      return client
-    end
+  module Authentication
+    def self.login(client = nil, log = nil, app_id: nil, installation_id: nil, app_key: nil, app_algo: nil)
+      # if the client is not nil, use the pre-provided client
+      unless client.nil?
+        log.debug("using pre-provided client") if log
+        return client
+      end
 
-    # if the client is nil, check for GitHub App env vars first
-    # first, check if all three of the following env vars are set and have values
-    # ISSUE_DB_GITHUB_APP_ID, ISSUE_DB_GITHUB_APP_INSTALLATION_ID, ISSUE_DB_GITHUB_APP_KEY
-    app_id = ENV.fetch("ISSUE_DB_GITHUB_APP_ID", nil)
-    installation_id = ENV.fetch("ISSUE_DB_GITHUB_APP_INSTALLATION_ID", nil)
-    app_key = ENV.fetch("ISSUE_DB_GITHUB_APP_KEY", nil)
-    if app_id && installation_id && app_key
-      log.debug("using github app authentication") if log
-      return GitHub.new(log:, app_id:, installation_id:, app_key:)
-    end
+      # if GitHub App parameters are provided, use them first
+      if app_id && installation_id && app_key
+        log.debug("using provided github app authentication parameters") if log
+        return IssueDB::Utils::GitHub.new(log:, app_id:, installation_id:, app_key:, app_algo:)
+      end
 
-    # if the client is nil and no GitHub App env vars were found, check for the ISSUE_DB_GITHUB_TOKEN
-    token = ENV.fetch("ISSUE_DB_GITHUB_TOKEN", nil)
-    if token
-      log.debug("using github token authentication") if log
-      octokit = Octokit::Client.new(access_token: token, page_size: 100)
-      octokit.auto_paginate = true
-      return octokit
-    end
+      # if the client is nil, check for GitHub App env vars
+      # first, check if all three of the following env vars are set and have values
+      # ISSUE_DB_GITHUB_APP_ID, ISSUE_DB_GITHUB_APP_INSTALLATION_ID, ISSUE_DB_GITHUB_APP_KEY
+      env_app_id = ENV.fetch("ISSUE_DB_GITHUB_APP_ID", nil)
+      env_installation_id = ENV.fetch("ISSUE_DB_GITHUB_APP_INSTALLATION_ID", nil)
+      env_app_key = ENV.fetch("ISSUE_DB_GITHUB_APP_KEY", nil)
+      if env_app_id && env_installation_id && env_app_key
+        log.debug("using github app authentication from environment variables") if log
+        return IssueDB::Utils::GitHub.new(log:, app_id: env_app_id, installation_id: env_installation_id, app_key: env_app_key)
+      end
 
-    # if we make it here, no valid auth method succeeded
-    raise AuthenticationError, "No valid GitHub authentication method was provided"
+      # if the client is nil and no GitHub App env vars were found, check for the ISSUE_DB_GITHUB_TOKEN
+      token = ENV.fetch("ISSUE_DB_GITHUB_TOKEN", nil)
+      if token
+        log.debug("using github token authentication") if log
+        octokit = Octokit::Client.new(access_token: token, page_size: 100)
+        octokit.auto_paginate = true
+        return octokit
+      end
+
+      # if we make it here, no valid auth method succeeded
+      raise AuthenticationError, "No valid GitHub authentication method was provided"
+    end
   end
 end

data/lib/issue_db/cache.rb

@@ -1,27 +1,35 @@
 # frozen_string_literal: true
 
-module Cache
-  # A helper method to update all issues in the cache
-  # :return: The updated issue cache as a list of issues
-  def update_issue_cache!
-    @log.debug("updating issue cache")
+module IssueDB
+  module Cache
+    # A helper method to update all issues in the cache
+    # :return: The updated issue cache as a list of issues
+    def update_issue_cache!
+      @log.debug("updating issue cache")
 
-    # find all issues in the repo that were created by this library
-    query = "repo:#{@repo.full_name} label:#{@label}"
+      # find all issues in the repo that were created by this library
+      query = "repo:#{@repo.full_name} label:#{@label}"
 
-    search_response = nil
-    begin
-      # issues structure: { "total_count": 0, "incomplete_results": false, "items": [<issues>] }
-      search_response = @client.search_issues(query)
-    rescue StandardError => e
-      retry_err_msg = "error search_issues() call: #{e.message}"
-      @log.error(retry_err_msg)
-      raise retry_err_msg
-    end
+      search_response = nil
+      begin
+        # issues structure: { "total_count": 0, "incomplete_results": false, "items": [<issues>] }
+        search_response = @client.search_issues(query)
+      rescue StandardError => e
+        retry_err_msg = "error search_issues() call: #{e.message}"
+        @log.error(retry_err_msg)
+        raise StandardError, retry_err_msg
+      end
+
+      # Safety check to ensure search_response and items are not nil
+      if search_response.nil? || search_response.items.nil?
+        @log.error("search_issues returned nil response or nil items")
+        raise StandardError, "search_issues returned invalid response"
+      end
 
-    @log.debug("issue cache updated - cached #{search_response.total_count} issues")
-    @issues = search_response.items
-    @issues_last_updated = Time.now
-    return @issues
+      @log.debug("issue cache updated - cached #{search_response.total_count} issues")
+      @issues = search_response.items
+      @issues_last_updated = Time.now
+      return @issues
+    end
   end
 end

data/lib/issue_db/database.rb

@@ -4,196 +4,220 @@ require_relative "cache"
 require_relative "models/record"
 require_relative "utils/generate"
 
-class RecordNotFound < StandardError; end
-
-class Database
-  include Cache
-  include Generate
-
-  # :param: log [Logger] a logger object to use for logging
-  # :param: client [Octokit::Client] an Octokit::Client object to use for interacting with the GitHub API
-  # :param: repo [Repository] a Repository object that represents the GitHub repository to use as the datastore
-  # :param: label [String] the label to use for issues managed in the datastore by this library
-  # :param: cache_expiry [Integer] the number of seconds to cache issues in memory (default: 60)
-  # :return: A new Database object
-  def initialize(log, client, repo, label, cache_expiry)
-    @log = log
-    @client = client
-    @repo = repo
-    @label = label
-    @cache_expiry = cache_expiry
-    @issues = nil
-    @issues_last_updated = nil
-  end
+module IssueDB
+  class RecordNotFound < StandardError; end
+
+  class Database
+    include Cache
+    include Generate
+
+    # :param: log [Logger] a logger object to use for logging
+    # :param: client [Octokit::Client] an Octokit::Client object to use for interacting with the GitHub API
+    # :param: repo [Repository] a Repository object that represents the GitHub repository to use as the datastore
+    # :param: label [String] the label to use for issues managed in the datastore by this library
+    # :param: cache_expiry [Integer] the number of seconds to cache issues in memory (default: 60)
+    # :return: A new Database object
+    def initialize(log, client, repo, label, cache_expiry)
+      @log = log
+      @client = client
+      @repo = repo
+      @label = label
+      @cache_expiry = cache_expiry
+      @issues = nil
+      @issues_last_updated = nil
+    end
 
-  # Create a new issue/record in the database
-  # This will return the newly created issue as a Record object (parsed)
-  # :param: key [String] the key (issue title) to create
-  # :param: data [Hash] the data to use for the issue body
-  # :param: options [Hash] a hash of options containing extra data such as body_before and body_after
-  # :return: The newly created issue as a Record object
-  # usage example:
-  # data = { color: "blue", cool: true, popularity: 100, tags: ["tag1", "tag2"] }
-  # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true }
-  # db.create("event123", {cool: true, data: "here"}, options)
-  def create(key, data, options = {})
-    @log.debug("attempting to create: #{key}")
-    issue = find_issue_by_key(key, options, create_mode: true)
-    if issue
-      @log.warn("skipping issue creation and returning existing issue - an issue already exists with the key: #{key}")
+    # Create a new issue/record in the database
+    # This will return the newly created issue as a Record object (parsed)
+    # :param: key [String] the key (issue title) to create
+    # :param: data [Hash] the data to use for the issue body
+    # :param: options [Hash] a hash of options containing extra data such as body_before and body_after
+    # :return: The newly created issue as a Record object
+    # usage example:
+    # data = { color: "blue", cool: true, popularity: 100, tags: ["tag1", "tag2"] }
+    # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true }
+    # db.create("event123", {cool: true, data: "here"}, options)
+    def create(key, data, options = {})
+      @log.debug("attempting to create: #{key}")
+      issue = find_issue_by_key(key, options, create_mode: true)
+      if issue
+        @log.warn("skipping issue creation and returning existing issue - an issue already exists with the key: #{key}")
+        return Record.new(issue)
+      end
+
+      # if we make it here, no existing issues were found so we can safely create one
+
+      body = generate(data, body_before: options[:body_before], body_after: options[:body_after])
+
+      # if we make it here, no existing issues were found so we can safely create one
+      issue = @client.create_issue(@repo.full_name, key, body, { labels: @label })
+
+      # ensure the cache is initialized before appending and handle race conditions
+      current_issues = issues
+      if current_issues && !current_issues.include?(issue)
+        @issues << issue
+      end
+
+      @log.debug("issue created: #{key}")
       return Record.new(issue)
     end
 
-    # if we make it here, no existing issues were found so we can safely create one
-
-    body = generate(data, body_before: options[:body_before], body_after: options[:body_after])
-
-    # if we make it here, no existing issues were found so we can safely create one
-    issue = @client.create_issue(@repo.full_name, key, body, { labels: @label })
-
-    # append the newly created issue to the issues cache
-    @issues << issue
-
-    @log.debug("issue created: #{key}")
-    return Record.new(issue)
-  end
-
-  # Read an issue/record from the database
-  # This will return the issue as a Record object (parsed)
-  # :param: key [String] the key (issue title) to read
-  # :param: options [Hash] a hash of options to pass through to the search method
-  # :return: The issue as a Record object
-  def read(key, options = {})
-    @log.debug("attempting to read: #{key}")
-    issue = find_issue_by_key(key, options)
-    @log.debug("issue found: #{key}")
-    return Record.new(issue)
-  end
-
-  # Update an issue/record in the database
-  # This will return the updated issue as a Record object (parsed)
-  # :param: key [String] the key (issue title) to update
-  # :param: data [Hash] the data to use for the issue body
-  # :param: options [Hash] a hash of options containing extra data such as body_before and body_after
-  # :return: The updated issue as a Record object
-  # usage example:
-  # data = { color: "blue", cool: true, popularity: 100, tags: ["tag1", "tag2"] }
-  # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true }
-  # db.update("event123", {cool: true, data: "here"}, options)
-  def update(key, data, options = {})
-    @log.debug("attempting to update: #{key}")
-    issue = find_issue_by_key(key, options)
-
-    body = generate(data, body_before: options[:body_before], body_after: options[:body_after])
-
-    updated_issue = @client.update_issue(@repo.full_name, issue.number, key, body)
-
-    # update the issue in the cache using the reference we have
-    @issues[@issues.index(issue)] = updated_issue
-
-    @log.debug("issue updated: #{key}")
-    return Record.new(updated_issue)
-  end
-
-  # Delete an issue/record from the database - in this context, "delete" means to close the issue as "completed"
-  # :param: key [String] the key (issue title) to delete
-  # :param: options [Hash] a hash of options to pass through to the search method
-  # :return: The deleted issue as a Record object (parsed) - it may contain useful data
-  def delete(key, options = {})
-    @log.debug("attempting to delete: #{key}")
-    issue = find_issue_by_key(key, options)
-
-    deleted_issue = @client.close_issue(@repo.full_name, issue.number)
-
-    # remove the issue from the cache
-    @issues.delete(issue)
-
-    # return the deleted issue as a Record object as it may contain useful data
-    return Record.new(deleted_issue)
-  end
+    # Read an issue/record from the database
+    # This will return the issue as a Record object (parsed)
+    # :param: key [String] the key (issue title) to read
+    # :param: options [Hash] a hash of options to pass through to the search method
+    # :return: The issue as a Record object
+    def read(key, options = {})
+      @log.debug("attempting to read: #{key}")
+      issue = find_issue_by_key(key, options)
+      @log.debug("issue found: #{key}")
+      return Record.new(issue)
+    end
 
-  # List all keys in the database
-  # This will return an array of strings that represent the issue titles that are "keys" in the database
-  # :param: options [Hash] a hash of options to pass through to the search method
-  # :return: An array of strings that represent the issue titles that are "keys" in the database
-  # usage example:
-  # options = {include_closed: true}
-  # keys = db.list_keys(options)
-  def list_keys(options = {})
-    keys = issues.select do |issue|
-      options[:include_closed] || issue[:state] == "open"
-    end.map do |issue|
-      issue[:title]
+    # Update an issue/record in the database
+    # This will return the updated issue as a Record object (parsed)
+    # :param: key [String] the key (issue title) to update
+    # :param: data [Hash] the data to use for the issue body
+    # :param: options [Hash] a hash of options containing extra data such as body_before and body_after
+    # :return: The updated issue as a Record object
+    # usage example:
+    # data = { color: "blue", cool: true, popularity: 100, tags: ["tag1", "tag2"] }
+    # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true }
+    # db.update("event123", {cool: true, data: "here"}, options)
+    def update(key, data, options = {})
+      @log.debug("attempting to update: #{key}")
+      issue = find_issue_by_key(key, options)
+
+      body = generate(data, body_before: options[:body_before], body_after: options[:body_after])
+
+      updated_issue = @client.update_issue(@repo.full_name, issue.number, key, body)
+
+      # update the issue in the cache using the reference we have
+      index = @issues.index(issue)
+      if index
+        @issues[index] = updated_issue
+      else
+        @log.warn("issue not found in cache during update: #{key}")
+        # Force a cache refresh to ensure consistency
+        update_issue_cache!
+      end
+
+      @log.debug("issue updated: #{key}")
+      return Record.new(updated_issue)
     end
 
-    return keys
-  end
+    # Delete an issue/record from the database - in this context, "delete" means to close the issue as "completed"
+    # :param: key [String] the key (issue title) to delete
+    # :param: options [Hash] a hash of options to pass through to the search method
+    # :return: The deleted issue as a Record object (parsed) - it may contain useful data
+    def delete(key, options = {})
+      @log.debug("attempting to delete: #{key}")
+      issue = find_issue_by_key(key, options)
+
+      deleted_issue = @client.close_issue(@repo.full_name, issue.number)
+
+      # update the issue in the cache using the reference we have
+      index = @issues.index(issue)
+      if index
+        @issues[index] = deleted_issue
+      else
+        @log.warn("issue not found in cache during delete: #{key}")
+        # Force a cache refresh to ensure consistency
+        update_issue_cache!
+      end
+
+      # return the deleted issue as a Record object as it may contain useful data
+      return Record.new(deleted_issue)
+    end
 
-  # List all issues/record in the database as Record objects (parsed)
-  # This will return an array of Record objects that represent the issues in the database
-  # :param: options [Hash] a hash of options to pass through to the search method
-  # :return: An array of Record objects that represent the issues in the database
-  # usage example:
-  # options = {include_closed: true}
-  # records = db.list(options)
-  def list(options = {})
-    records = issues.select do |issue|
-      options[:include_closed] || issue[:state] == "open"
-    end.map do |issue|
-      Record.new(issue)
+    # List all keys in the database
+    # This will return an array of strings that represent the issue titles that are "keys" in the database
+    # :param: options [Hash] a hash of options to pass through to the search method
+    # :return: An array of strings that represent the issue titles that are "keys" in the database
+    # usage example:
+    # options = {include_closed: true}
+    # keys = db.list_keys(options)
+    def list_keys(options = {})
+      current_issues = issues
+      return [] if current_issues.nil?
+
+      keys = current_issues.select do |issue|
+        options[:include_closed] || issue[:state] == "open"
+      end.map do |issue|
+        issue[:title]
+      end
+
+      return keys
     end
 
-    return records
-  end
+    # List all issues/record in the database as Record objects (parsed)
+    # This will return an array of Record objects that represent the issues in the database
+    # :param: options [Hash] a hash of options to pass through to the search method
+    # :return: An array of Record objects that represent the issues in the database
+    # usage example:
+    # options = {include_closed: true}
+    # records = db.list(options)
+    def list(options = {})
+      current_issues = issues
+      return [] if current_issues.nil?
+
+      records = current_issues.select do |issue|
+        options[:include_closed] || issue[:state] == "open"
+      end.map do |issue|
+        Record.new(issue)
+      end
+
+      return records
+    end
 
-  # Force a refresh of the issues cache
-  # This will update the issues cache with the latest issues from the repo
-  # :return: The updated issue cache as a list of issues (Hash objects not parsed)
-  def refresh!
-    update_issue_cache!
-  end
+    # Force a refresh of the issues cache
+    # This will update the issues cache with the latest issues from the repo
+    # :return: The updated issue cache as a list of issues (Hash objects not parsed)
+    def refresh!
+      update_issue_cache!
+    end
 
   protected
 
-  def not_found!(key)
-    raise RecordNotFound, "no record found for key: #{key}"
-  end
-
-  # A helper method to search through the issues cache and return the first issue that matches the given key
-  # :param: key [String] the key (issue title) to search for
-  # :param: options [Hash] a hash of options to pass through to the search method
-  # :param: create_mode [Boolean] a flag to indicate whether or not we are in create mode
-  # :return: A direct reference to the issue as a Hash object if found, otherwise throws a RecordNotFound error
-  # ... unless create_mode is true, in which case it returns nil as a signal to proceed with creating the issue
-  def find_issue_by_key(key, options = {}, create_mode: false)
-    issue = issues.find do |issue|
-      issue[:title] == key && (options[:include_closed] || issue[:state] == "open")
+    def not_found!(key)
+      raise RecordNotFound, "no record found for key: #{key}"
     end
 
-    if issue.nil?
-      @log.debug("no issue found in cache for: #{key}")
-      return nil if create_mode
-
-      not_found!(key)
+    # A helper method to search through the issues cache and return the first issue that matches the given key
+    # :param: key [String] the key (issue title) to search for
+    # :param: options [Hash] a hash of options to pass through to the search method
+    # :param: create_mode [Boolean] a flag to indicate whether or not we are in create mode
+    # :return: A direct reference to the issue as a Hash object if found, otherwise throws a RecordNotFound error
+    # ... unless create_mode is true, in which case it returns nil as a signal to proceed with creating the issue
+    def find_issue_by_key(key, options = {}, create_mode: false)
+      issue = issues.find do |issue|
+        issue[:title] == key && (options[:include_closed] || issue[:state] == "open")
+      end
+
+      if issue.nil?
+        @log.debug("no issue found in cache for: #{key}")
+        return nil if create_mode
+
+        not_found!(key)
+      end
+
+      @log.debug("issue found in cache for: #{key}")
+      return issue
     end
 
-    @log.debug("issue found in cache for: #{key}")
-    return issue
-  end
+    # A helper method to fetch all issues from the repo and update the issues cache
+    # It is cache aware
+    def issues
+      # update the issues cache if it is nil
+      update_issue_cache! if @issues.nil?
 
-  # A helper method to fetch all issues from the repo and update the issues cache
-  # It is cache aware
-  def issues
-    # update the issues cache if it is nil
-    update_issue_cache! if @issues.nil?
+      # update the cache if it has expired (with nil safety)
+      if !@issues_last_updated.nil? && (Time.now - @issues_last_updated) > @cache_expiry
+        @log.debug("issue cache expired - last updated: #{@issues_last_updated} - refreshing now")
+        update_issue_cache!
+      end
 
-    # update the cache if it has expired
-    issues_cache_expired = (Time.now - @issues_last_updated) > @cache_expiry
-    if issues_cache_expired
-      @log.debug("issue cache expired - last updated: #{@issues_last_updated} - refreshing now")
-      update_issue_cache!
+      return @issues
     end
-
-    return @issues
   end
 end