octokitted 0.0.8 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7fe4c051e60f41068c020cd9c0fbfe3bae4d1cb673e22de5dc17c3b76e46ea9
-  data.tar.gz: b6c569962b05022e655a077f9f692c5d17a2bab406e29722188887dc7be248cc
+  metadata.gz: 986492cc42b62e6430a462513f232ad56788e51208ca6e6cfaf6560a37b22f81
+  data.tar.gz: 266493071acbdae5115a6bea0ef739f89c6cafc07883f165df38db6d59c9db1e
 SHA512:
-  metadata.gz: b3a9add54171018622c44d309e6ac50435d3c225fe4795eb917c9812a3a567881210fa8f538b6b575eb00cb7bc7d2831da3899cfa9f29115ef30ce42fffa384f
-  data.tar.gz: 2cb81e5b5a4e078cfc7dec09202092c01c609a888ffc2c6e176390f45de1ebcdd3f4c9873378a90ccd33fddc4d4425493846af1288886ee2f1489a7e38432dbe
+  metadata.gz: 1b80f268701244a188b1a5508ff53089d84da3b2db5873003b10426fd91bf4814a7b2a4609861ee4d822df6c7d74834512740ced1c9233eeb98c44c4c3d63b22
+  data.tar.gz: 5355f24848030b3e248c1cdc45b1769d1a5332da6c18bff43fcdb07e38ee7e7dffe1973034c39ddf1742a22574b00f6ceeab3e166413e22e02103746a0ac9469

data/README.md

@@ -11,3 +11,169 @@ A self-hydrating version of Octokit for usage in CI systems - like GitHub Action
 > "we were all kitted out in life jackets", "our octokit client was kitted out for CI usage"
 
 ![octokitted](./docs/assets/dalle.png)
+
+## Installation 💎
+
+You can download this Gem from either [RubyGems](https://rubygems.org/gems/octokitted) or [GitHub Packages](https://github.com/GrantBirki/octokitted/pkgs/rubygems/octokitted)
+
+RubyGems (Recommended):
+
+```bash
+gem install octokitted
+```
+
+> RubyGems [link](https://rubygems.org/gems/octokitted)
+
+Via a Gemfile:
+
+```ruby
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "octokit", "~> 7.1" # a dependency of octokitted
+gem "octokitted", "~> X.X.X" # Replace X.X.X with the latest version
+```
+
+## Usage 💻
+
+This section goes over general usage of this Gem
+
+For full usage documentation of available methods, please see the [docs](./docs/usage.md)
+
+### Configuration
+
+The following table goes into detail about the configuration options that can be passed into the `Octokitted.new()` constructor:
+
+> It should be noted that when calling `Octokitted.new()` in the proper GitHub Action's context, no configuration is required to be passed into `.new()` because this Gem will fully self-hydrate itself. The `Required` field is only in the table below for reference if you are not running this Gem in GitHub Actions.
+
+| Option | Environment Variable | Description | Required |
+| ------ | -------------------- | ----------- | -------- |
+| `login` | - | The GitHub handle associated with the provided `token`. Defaults to the owner of the token | no |
+| `org` | `GITHUB_REPOSITORY` | The GitHub organization or user that owns a given repository. This value self-hydrates from the `GITHUB_REPOSITORY` env var when run in GitHub Actions | no, can be set after construction |
+| `repo` | `GITHUB_REPOSITORY` | The GitHub repository name. This value self-hydrates from the `GITHUB_REPOSITORY` env var when run in GitHub Actions | no, can be set after construction |
+| `issue_number` | `GITHUB_EVENT_PATH` | The GitHub issue number. This value self-hydrates from the `GITHUB_EVENT_PATH` env var when run in GitHub Actions. The event json object is read from disk on the Action's runner which contains issue number information | no, can be set after construction |
+| `token` | `GITHUB_TOKEN` or `OCTOKIT_ACCESS_TOKEN` | The GitHub token to use for authentication. This value self-hydrates from the `GITHUB_TOKEN` env var when run in GitHub Actions | yes, required for construction |
+| `logger` | - | The logger to use for logging. You can pass in your own logger or use the one this Gem auto-creates by default | no |
+
+It should be noted that you can configure the log level that is used through the `LOG_LEVEL` environment variable. The default log level is `INFO`.
+
+### GitHub Actions
+
+If you are running in the context of a **pull request** or an **issue** in GitHub Actions, you can simply create a new instance of `Octokitted` and it will automatically hydrate itself:
+
+```ruby
+# frozen_string_literal: true
+
+require "octokitted"
+
+# Setup a new instance of Octokitted and self-hydrate
+gh = Octokitted.new()
+
+puts "#{gh.org} #{gh.repo} #{gh.org_and_repo}"
+# => GrantBirki octokitted GrantBirki/octokitted
+
+puts gh.issue_number
+# => 123
+
+# add a comment to the issue in the context we are running in
+gh.issue.add_comment(comment: "Hello from Octokitted!")
+
+# add a label to the issue
+gh.issue.add_labels(labels: ["test"])
+
+# remove the label from the issue
+gh.issue.remove_labels(labels: ["test"])
+
+# close the issue
+gh.issue.close
+
+# swap your context to a different issue
+gh.issue_number = 456
+puts gh.issue_number
+# => 456
+
+```
+
+### Outside of GitHub Actions
+
+If you want to use Octokitted outside of GitHub Actions, you can pass some of the required information to the constructor:
+
+```ruby
+# frozen_string_literal: true
+
+require "octokitted"
+
+# Setup a new instance of Octokitted with explicit values
+gh = Octokitted.new(
+    login: "GrantBirki", # The user associated with the GITHUB_TOKEN
+    org: "GrantBirki", # The organization associated with the repo
+    repo: "octokitted", # The repo name
+    token: ENV.fetch("GITHUB_TOKEN"), # The GitHub token to use
+    issue_number: 123 # The issue number to use
+)
+
+# Now you have an octokitted client that is hydrated and ready to use just as seen in the more detailed example above!
+
+puts "#{gh.org} #{gh.repo} #{gh.org_and_repo}"
+# => GrantBirki octokitted GrantBirki/octokitted
+
+puts gh.issue_number
+# => 123
+
+# ...
+```
+
+### Native Git Usage
+
+If you system / container has the `git` binary installed, you can also use this Gem to run native Git commands:
+
+```ruby
+# frozen_string_literal: true
+
+require "octokitted"
+
+# Setup a new instance of Octokitted with explicit values
+gh = Octokitted.new(
+    login: "GrantBirki", # The user associated with the GITHUB_TOKEN
+    org: "GrantBirki", # The organization associated with the repo
+    repo: "octokitted", # The repo name
+    token: ENV.fetch("GITHUB_TOKEN") # The GitHub token to use
+)
+
+# Check to see if there are any cloned repos
+puts gh.cloned_repos
+# => []
+
+# Clone the repo we setup our client with and get back a Git::Base object
+git = gh.clone
+
+# Check again to see that we have one locally cloned repo at the path displayed
+puts gh.cloned_repos
+# => ["./octokitted"]
+
+git.checkout("new_branch", new_branch: true, start_point: "main")
+
+git.add # git add -- "."
+# git.add(:all=>true) # git add --all -- "."
+# git.add("file_path") # git add -- "file_path"
+# git.add(["file_path_1", "file_path_2"])
+
+git.commit("message")
+# git.commit_all("message")
+
+git.push
+# git.push(git.remote("name"))
+
+# remove the repo we just cloned
+gh.remove_all_clones!
+
+puts gh.cloned_repos
+# => []
+```
+
+> Read more about the native Git Ruby Gem [here](https://github.com/ruby-git/ruby-git)
+
+## Release 🚀
+
+To release a new version of this gem, simply edit the [`lib/version.rb`](lib/version.rb) in this repo. When you commit your changes to `main`, a new version will be automatically released via GitHub Actions to RubyGems and GitHub Packages.

data/lib/octokitted/common/issue.rb

@@ -43,8 +43,8 @@ class Issue
   # Adds a comment to an issue or pull request
   # :param comment: The comment to add to the issue (String)
   # :param issue_number: The issue number to add the comment to
-  Contract KeywordArgs[comment: String, issue_number: Maybe[Numeric]] => Any
-  def add_comment(comment:, issue_number: nil)
+  Contract String, KeywordArgs[issue_number: Maybe[Numeric]] => Any
+  def add_comment(comment, issue_number: nil)
     issue_number = construct_issue_numer(issue_number)
     @log.debug("adding comment: #{comment} to issue: #{issue_number}")
 

data/lib/octokitted.rb

@@ -62,6 +62,15 @@ class Octokitted
     @log.debug("repo: #{@repo}")
   end
 
+  # Setter method for the issue_number instance variable
+  # :param issue_number: The issue_number to set
+  # :return: it does not return as it is a setter method
+  Contract Numeric => Any
+  def issue_number=(issue_number)
+    @issue_number = issue_number
+    @log.debug("updated issue_number: #{@issue_number}")
+  end
+
   # Setter method for the repo instance variable
   # :param repo: The repo to set
   # :return: it does not return as it is a setter method
@@ -159,6 +168,10 @@ class Octokitted
   # :return: A Hash of the GitHub event data or nil if not found
   Contract Maybe[String] => Maybe[Hash]
   def fetch_github_event(event_path)
+    if ENV.fetch("GITHUB_ACTIONS", nil).nil?
+      @log.debug("Not running in GitHub Actions - GitHub Event data not auto-hydrated")
+      return nil
+    end
     unless event_path
       @log.warn("GITHUB_EVENT_PATH env var not found")
       return nil

data/lib/version.rb

@@ -2,6 +2,6 @@
 
 module Octokitted
   module Version
-    VERSION = "0.0.8"
+    VERSION = "1.0.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: octokitted
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 1.0.0
 platform: ruby
 authors:
 - Grant Birkinbine