Quick Start ⚡

require"issue_db"# The GitHub repository to use as the databaserepo="runwaylab/grocery-orders"# Create a new database instancedb=IssueDB.new(repo)# Write a new record to the databasedb.create("order_number_123",{location:"London",items:["cookies","espresso"]})# Read the newly created record from the databaserecord=db.read("order_number_123")putsrecord.data# => {location: "London", items: ["cookies", "espresso"]}

Installation 🚚

source"https://rubygems.org"gem"issue-db","X.X.X"# Replace X.X.X with the version you want to use

source"https://rubygems.pkg.github.com/runwaylab"dogem"issue-db","X.X.X"# Replace X.X.X with the version you want to useend

gem install issue-db --version"X.X.X"

Usage 💻

Important

The key for the record is the title of the GitHub issue. This means that the keymust 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), theissue-db gem will return the existing record without modifying it. Here is an example log message where someone callsdb.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 = {})

record=db.create("order_number_123",{location:"London",items:["cookies","espresso"]})# with the `body_before` and `body_after` options to add markdown text before and after the data in the GitHub issue body# this can be useful if you want to add additional context to the data in the issue body for humans to read# more on this in another section of the README belowoptions={body_before:"some markdown text before the data",body_after:"some markdown text after the data"}record=db.create("order_number_123",{location:"London",items:["cookies","espresso"]},options)# with the `labels` option to add additional GitHub labels to the issue (in addition to the library-managed label)options={labels:["priority:high","customer:premium"]}record=db.create("order_number_123",{location:"London",items:["cookies","espresso"]},options)# with the `assignees` option to assign GitHub users to the issueoptions={assignees:["alice","bob"]}record=db.create("order_number_123",{location:"London",items:["cookies","espresso"]},options)# with multiple options combinedoptions={labels:["priority:high","customer:premium"],assignees:["alice","bob"],body_before:"some markdown text before the data",body_after:"some markdown text after the data"}record=db.create("order_number_123",{location:"London",items:["cookies","espresso"]},options)

db.read(key, options = {})

record=db.read("order_number_123")# with the `include_closed` option to include records that have been deleted (i.e. the GitHub issue is closed)options={include_closed:true}record=db.read("order_number_123",options)

db.update(key, data, options = {})

record=db.update("order_number_123",{location:"London",items:["cookies","espresso","chips"]})# with the `body_before` and `body_after` options to add markdown text before and after the data in the GitHub issue body# this can be useful if you want to add additional context to the data in the issue body for humans to read# more on this in another section of the README belowoptions={body_before:"# Order 123\n\nData:",body_after:"Please do not edit the body of this issue"}record=db.update("order_number_123",{location:"London",items:["cookies","espresso","chips"]},options)# with the `labels` option to add additional GitHub labels to the issue (in addition to the library-managed label)options={labels:["status:processed","priority:low"]}record=db.update("order_number_123",{location:"London",items:["cookies","espresso","chips"]},options)# with the `assignees` option to assign GitHub users to the issueoptions={assignees:["charlie","diana"]}record=db.update("order_number_123",{location:"London",items:["cookies","espresso","chips"]},options)# with multiple options combinedoptions={labels:["status:processed","priority:low"],assignees:["charlie","diana"],body_before:"# Order 123\n\nData:",body_after:"Please do not edit the body of this issue"}record=db.update("order_number_123",{location:"London",items:["cookies","espresso","chips"]},options)

db.delete(key, options = {})

record=db.delete("order_number_123")# with the `labels` option to add additional GitHub labels to the issue before closing itoptions={labels:["archived","completed"]}record=db.delete("order_number_123",options)# with the `assignees` option to assign GitHub users to the issue before closing itoptions={assignees:["alice"]}record=db.delete("order_number_123",options)# with multiple options combinedoptions={labels:["archived","completed"],assignees:["alice"]}record=db.delete("order_number_123",options)

db.list_keys(options = {})

keys=db.list_keys# with the `include_closed` option to include records that have been deleted (i.e. the GitHub issue is closed)options={include_closed:true}keys=db.list_keys(options)

db.list(options = {})

records=db.list# with the `include_closed` option to include records that have been deleted (i.e. the GitHub issue is closed)options={include_closed:true}records=db.list(options)

db.refresh!

db.refresh!

Options 🛠

Environment Variables 🌍

Labels 🏷️

Library-Managed Label

Additional Custom Labels

# Add custom labels when creating a recordoptions={labels:["priority:high","customer:premium","region:europe"]}record=db.create("order_123",{product:"laptop"},options)# Add custom labels when updating a recordoptions={labels:["status:processed","priority:low"]}record=db.update("order_123",{product:"laptop",status:"shipped"},options)# Add custom labels before deleting (closing) a recordoptions={labels:["archived","completed","Q4-2024"]}record=db.delete("order_123",options)

Label Preservation

# Create a record with custom labelsoptions={labels:["priority:high","customer:premium"]}record=db.create("order_123",{product:"laptop"},options)# Result: Issue has labels ["issue-db", "priority:high", "customer:premium"]# Update the record WITHOUT specifying labels - existing labels are preservedrecord=db.update("order_123",{product:"laptop",status:"shipped"})# Result: Issue STILL has labels ["issue-db", "priority:high", "customer:premium"]# Update the record WITH new labels - replaces all labels (except library-managed)options={labels:["status:processed","priority:low"]}record=db.update("order_123",{product:"laptop",status:"delivered"},options)# Result: Issue now has labels ["issue-db", "status:processed", "priority:low"]

Example with Multiple Options

options={labels:["priority:high","customer:vip"],body_before:"## Order Details\n\nCustomer: VIP\n\n",body_after:"\n\n---\n*This order requires special handling*"}record=db.create("vip_order_456",{items:["premium_service"]},options)

Assignees 👥

Basic Assignee Usage

# Assign users when creating a recordoptions={assignees:["alice","bob"]}record=db.create("task_123",{type:"code_review"},options)# Assign users when updating a recordoptions={assignees:["charlie","diana"]}record=db.update("task_123",{type:"code_review",status:"in_progress"},options)# Assign users before deleting (closing) a recordoptions={assignees:["alice"]}record=db.delete("task_123",options)

Assignee Preservation

# Create a record with assigneesoptions={assignees:["alice","bob"]}record=db.create("task_123",{type:"code_review"},options)# Result: Issue is assigned to alice and bob# Update the record WITHOUT specifying assignees - existing assignees are preservedrecord=db.update("task_123",{type:"code_review",status:"in_progress"})# Result: Issue is STILL assigned to alice and bob# Update the record WITH new assignees - replaces all assigneesoptions={assignees:["charlie"]}record=db.update("task_123",{type:"code_review",status:"completed"},options)# Result: Issue is now only assigned to charlie

Combining Labels and Assignees

options={labels:["priority:high","type:bug","team:backend"],assignees:["alice","bob"],body_before:"## Bug Report\n\nPriority: High\nTeam: Backend\n\n",body_after:"\n\n---\n*Assigned to backend team leads*"}record=db.create("bug_456",{error:"Database timeout",severity:"critical"},options)

Authentication 🔒

Using a GitHub Personal Access Token

# Assuming you have a GitHub personal access token set as the ISSUE_DB_GITHUB_TOKEN env varrequire"issue_db"db=IssueDB.new("<org>/<repo>")# THAT'S IT! 🎉

Using GitHub App Parameters Directly

require"issue_db"# Pass GitHub App credentials directly to IssueDB.newdb=IssueDB.new("<org>/<repo>",app_id:12345,# Your GitHub App IDinstallation_id:56789,# Your GitHub App Installation IDapp_key:"-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",# Your GitHub App private keyapp_algo:"RS256"# Optional: defaults to RS256)

Using a GitHub App with Environment Variables

# Assuming you have the following three environment variables set:# 1: ISSUE_DB_GITHUB_APP_ID# app ids are found on the App's settings page# 2: ISSUE_DB_GITHUB_APP_INSTALLATION_ID# installation ids look like this:# https://github.com/organizations/<org>/settings/installations/<8_digit_id># 3. ISSUE_DB_GITHUB_APP_KEY# app keys are found on the App's settings page and can be downloaded# format: "-----BEGIN...key\n...END-----\n" (this will be one super long string and that's okay)# make sure this key in your env is a single line string with newlines as "\n"# With all three of these environment variables set, you can proceed with ease!db=IssueDB.new("<org>/<repo>")# THAT'S IT! 🎉

Using Your Own AuthenticatedOctokit.rb Instance

require"octokit"# Create your own authenticated Octokit.rb instance# You should probably set the page_size to 100 and auto_paginate to trueoctokit=Octokit::Client.new(access_token:"<TOKEN>",page_size:100)octokit.auto_paginate=truedb=IssueDB.new("<org>/<repo>",octokit_client:octokit)

Advanced Example 🚀

# Assuming you have a GitHub personal access token set as the ISSUE_DB_GITHUB_TOKEN env varrequire"issue_db"# The GitHub repository to use as the databaserepo="runwaylab/grocery-orders"# Create a new database instancedb=IssueDB.new(repo)# Write a new record to the database where the title of the issue is the unique keynew_issue=db.create("order_number_123",{location:"London",items:["cookies","espresso"]})# View the record data and the source data which contains the GitHub issue objectputsnew_issue.data# => {location: "London", items: ["cookies", "espresso"]}putsnew_issue.source_data.state# => "open" (the GitHub issue is open so the record is active)putsnew_issue.source_data.html_url# => "https://github.com/runwaylab/grocery-orders/issues/<number>" (the URL of the GitHub issue which is the DB record)# Update the recordupdated_issue=db.update("order_number_123",{location:"London",items:["cookies","espresso","chips"]})# View the updated record dataputsupdated_issue.data# => {location: "London", items: ["cookies", "espresso", "chips"]}# Get the record by keyrecord=db.read("order_number_123")# View the record dataputsrecord.data# => {location: "London", items: ["cookies", "espresso", "chips"]}# Delete the recorddeleted_record=db.delete("order_number_123")putsdeleted_record.source_data.state# => "closed" (the GitHub issue is closed as "completed" so the record is inactive)# List all keys in the database including closed recordskeys=db.list_keys({include_closed:true})putskeys# => ["order_number_123"]# List all records in the database including closed recordsrecords=db.list({include_closed:true})# Inspection of the first record in the listputsrecords.first.data# => {location: "London", items: ["cookies", "espresso", "chips"]}putsrecords.first.source_data.state# => "closed" (the GitHub issue is closed as "completed" so the record is inactive)# Force a refresh of the database cache (useful if you have made changes to the database outside of the gem and don't want to wait for the cache to refresh)db.refresh!

Embedding Markdown in the Issue Body 📝

body_before_text=<<~BODY# Out of Date Operating System 🚨<!--- HUMANS: DO NOT EDIT THIS ISSUE BODY ;) -->It looks like your laptop is running an out of date operating system. This is a security risk.Please update your OS as soon as possible.## DetailsBODYbody_after_text=<<~BODY> Thank you for your attention to this matter.BODYoptions={body_before:body_before_text,body_after:body_after_text}data={operating_system:"macOS 1.2.3",last_updated_at:"2024-09-30",user:"Celeste",location:"California",out_of_date:true,employee_id:123}record=db.create("Out of Date OS - EmployeeID: 123",data,options)# this assumes that employee IDs are unique in this example

#Out of Date Operating System 🚨<!--- HUMANS: DO NOT EDIT THIS ISSUE BODY ;)-->It looks like your laptop is running an out of date operating system. This is a security risk.Please update your OS as soon as possible.##Details<!--- issue-db-start-->```json{"operating_system":"macOS 1.2.3","last_updated_at":"2024-09-30","user":"Celeste","location":"California","out_of_date":true}```<!--- issue-db-end-->>Thank you for your attention to this matter.

record=db.read("Out of Date OS - EmployeeID: 123")putsrecord.data# => {"operating_system"=>"macOS 1.2.3", "last_updated_at"=>"2024-09-30", "user"=>"Celeste", "location"=>"California", "out_of_date"=>true, "employee_id"=>123}putsrecord.body_before# the markdown text before the data in the issue body (as seen above, not going to repeat it here - its long)putsrecord.body_after# ditto ^# puts record.source_data.body # useful for getting the raw markdown text of the issue body as is

Record Attributes 📦

record=db.read("order_number_123")putsrecord.key# => "order_number_123"putsrecord.data# => { "location"=>"London", "items"=>[ "cookies", "espresso", "chips" ] }putsrecord.data["location"]# => "London"putsrecord.source_data.state# => "open" (the GitHub issue is open so the record is active)putsrecord.body_before# => "some markdown text before the data"putsrecord.body_after# => "some markdown text after the data"