octokitted 0.0.8 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c7fe4c051e60f41068c020cd9c0fbfe3bae4d1cb673e22de5dc17c3b76e46ea9
4
- data.tar.gz: b6c569962b05022e655a077f9f692c5d17a2bab406e29722188887dc7be248cc
3
+ metadata.gz: 986492cc42b62e6430a462513f232ad56788e51208ca6e6cfaf6560a37b22f81
4
+ data.tar.gz: 266493071acbdae5115a6bea0ef739f89c6cafc07883f165df38db6d59c9db1e
5
5
  SHA512:
6
- metadata.gz: b3a9add54171018622c44d309e6ac50435d3c225fe4795eb917c9812a3a567881210fa8f538b6b575eb00cb7bc7d2831da3899cfa9f29115ef30ce42fffa384f
7
- data.tar.gz: 2cb81e5b5a4e078cfc7dec09202092c01c609a888ffc2c6e176390f45de1ebcdd3f4c9873378a90ccd33fddc4d4425493846af1288886ee2f1489a7e38432dbe
6
+ metadata.gz: 1b80f268701244a188b1a5508ff53089d84da3b2db5873003b10426fd91bf4814a7b2a4609861ee4d822df6c7d74834512740ced1c9233eeb98c44c4c3d63b22
7
+ data.tar.gz: 5355f24848030b3e248c1cdc45b1769d1a5332da6c18bff43fcdb07e38ee7e7dffe1973034c39ddf1742a22574b00f6ceeab3e166413e22e02103746a0ac9469
data/README.md CHANGED
@@ -11,3 +11,169 @@ A self-hydrating version of Octokit for usage in CI systems - like GitHub Action
11
11
  > "we were all kitted out in life jackets", "our octokit client was kitted out for CI usage"
12
12
 
13
13
  ![octokitted](./docs/assets/dalle.png)
14
+
15
+ ## Installation 💎
16
+
17
+ You can download this Gem from either [RubyGems](https://rubygems.org/gems/octokitted) or [GitHub Packages](https://github.com/GrantBirki/octokitted/pkgs/rubygems/octokitted)
18
+
19
+ RubyGems (Recommended):
20
+
21
+ ```bash
22
+ gem install octokitted
23
+ ```
24
+
25
+ > RubyGems [link](https://rubygems.org/gems/octokitted)
26
+
27
+ Via a Gemfile:
28
+
29
+ ```ruby
30
+ # frozen_string_literal: true
31
+
32
+ source "https://rubygems.org"
33
+
34
+ gem "octokit", "~> 7.1" # a dependency of octokitted
35
+ gem "octokitted", "~> X.X.X" # Replace X.X.X with the latest version
36
+ ```
37
+
38
+ ## Usage 💻
39
+
40
+ This section goes over general usage of this Gem
41
+
42
+ For full usage documentation of available methods, please see the [docs](./docs/usage.md)
43
+
44
+ ### Configuration
45
+
46
+ The following table goes into detail about the configuration options that can be passed into the `Octokitted.new()` constructor:
47
+
48
+ > 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.
49
+
50
+ | Option | Environment Variable | Description | Required |
51
+ | ------ | -------------------- | ----------- | -------- |
52
+ | `login` | - | The GitHub handle associated with the provided `token`. Defaults to the owner of the token | no |
53
+ | `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 |
54
+ | `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 |
55
+ | `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 |
56
+ | `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 |
57
+ | `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 |
58
+
59
+ 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`.
60
+
61
+ ### GitHub Actions
62
+
63
+ 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:
64
+
65
+ ```ruby
66
+ # frozen_string_literal: true
67
+
68
+ require "octokitted"
69
+
70
+ # Setup a new instance of Octokitted and self-hydrate
71
+ gh = Octokitted.new()
72
+
73
+ puts "#{gh.org} #{gh.repo} #{gh.org_and_repo}"
74
+ # => GrantBirki octokitted GrantBirki/octokitted
75
+
76
+ puts gh.issue_number
77
+ # => 123
78
+
79
+ # add a comment to the issue in the context we are running in
80
+ gh.issue.add_comment(comment: "Hello from Octokitted!")
81
+
82
+ # add a label to the issue
83
+ gh.issue.add_labels(labels: ["test"])
84
+
85
+ # remove the label from the issue
86
+ gh.issue.remove_labels(labels: ["test"])
87
+
88
+ # close the issue
89
+ gh.issue.close
90
+
91
+ # swap your context to a different issue
92
+ gh.issue_number = 456
93
+ puts gh.issue_number
94
+ # => 456
95
+
96
+ ```
97
+
98
+ ### Outside of GitHub Actions
99
+
100
+ If you want to use Octokitted outside of GitHub Actions, you can pass some of the required information to the constructor:
101
+
102
+ ```ruby
103
+ # frozen_string_literal: true
104
+
105
+ require "octokitted"
106
+
107
+ # Setup a new instance of Octokitted with explicit values
108
+ gh = Octokitted.new(
109
+ login: "GrantBirki", # The user associated with the GITHUB_TOKEN
110
+ org: "GrantBirki", # The organization associated with the repo
111
+ repo: "octokitted", # The repo name
112
+ token: ENV.fetch("GITHUB_TOKEN"), # The GitHub token to use
113
+ issue_number: 123 # The issue number to use
114
+ )
115
+
116
+ # Now you have an octokitted client that is hydrated and ready to use just as seen in the more detailed example above!
117
+
118
+ puts "#{gh.org} #{gh.repo} #{gh.org_and_repo}"
119
+ # => GrantBirki octokitted GrantBirki/octokitted
120
+
121
+ puts gh.issue_number
122
+ # => 123
123
+
124
+ # ...
125
+ ```
126
+
127
+ ### Native Git Usage
128
+
129
+ If you system / container has the `git` binary installed, you can also use this Gem to run native Git commands:
130
+
131
+ ```ruby
132
+ # frozen_string_literal: true
133
+
134
+ require "octokitted"
135
+
136
+ # Setup a new instance of Octokitted with explicit values
137
+ gh = Octokitted.new(
138
+ login: "GrantBirki", # The user associated with the GITHUB_TOKEN
139
+ org: "GrantBirki", # The organization associated with the repo
140
+ repo: "octokitted", # The repo name
141
+ token: ENV.fetch("GITHUB_TOKEN") # The GitHub token to use
142
+ )
143
+
144
+ # Check to see if there are any cloned repos
145
+ puts gh.cloned_repos
146
+ # => []
147
+
148
+ # Clone the repo we setup our client with and get back a Git::Base object
149
+ git = gh.clone
150
+
151
+ # Check again to see that we have one locally cloned repo at the path displayed
152
+ puts gh.cloned_repos
153
+ # => ["./octokitted"]
154
+
155
+ git.checkout("new_branch", new_branch: true, start_point: "main")
156
+
157
+ git.add # git add -- "."
158
+ # git.add(:all=>true) # git add --all -- "."
159
+ # git.add("file_path") # git add -- "file_path"
160
+ # git.add(["file_path_1", "file_path_2"])
161
+
162
+ git.commit("message")
163
+ # git.commit_all("message")
164
+
165
+ git.push
166
+ # git.push(git.remote("name"))
167
+
168
+ # remove the repo we just cloned
169
+ gh.remove_all_clones!
170
+
171
+ puts gh.cloned_repos
172
+ # => []
173
+ ```
174
+
175
+ > Read more about the native Git Ruby Gem [here](https://github.com/ruby-git/ruby-git)
176
+
177
+ ## Release 🚀
178
+
179
+ 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.
@@ -43,8 +43,8 @@ class Issue
43
43
  # Adds a comment to an issue or pull request
44
44
  # :param comment: The comment to add to the issue (String)
45
45
  # :param issue_number: The issue number to add the comment to
46
- Contract KeywordArgs[comment: String, issue_number: Maybe[Numeric]] => Any
47
- def add_comment(comment:, issue_number: nil)
46
+ Contract String, KeywordArgs[issue_number: Maybe[Numeric]] => Any
47
+ def add_comment(comment, issue_number: nil)
48
48
  issue_number = construct_issue_numer(issue_number)
49
49
  @log.debug("adding comment: #{comment} to issue: #{issue_number}")
50
50
 
data/lib/octokitted.rb CHANGED
@@ -62,6 +62,15 @@ class Octokitted
62
62
  @log.debug("repo: #{@repo}")
63
63
  end
64
64
 
65
+ # Setter method for the issue_number instance variable
66
+ # :param issue_number: The issue_number to set
67
+ # :return: it does not return as it is a setter method
68
+ Contract Numeric => Any
69
+ def issue_number=(issue_number)
70
+ @issue_number = issue_number
71
+ @log.debug("updated issue_number: #{@issue_number}")
72
+ end
73
+
65
74
  # Setter method for the repo instance variable
66
75
  # :param repo: The repo to set
67
76
  # :return: it does not return as it is a setter method
@@ -159,6 +168,10 @@ class Octokitted
159
168
  # :return: A Hash of the GitHub event data or nil if not found
160
169
  Contract Maybe[String] => Maybe[Hash]
161
170
  def fetch_github_event(event_path)
171
+ if ENV.fetch("GITHUB_ACTIONS", nil).nil?
172
+ @log.debug("Not running in GitHub Actions - GitHub Event data not auto-hydrated")
173
+ return nil
174
+ end
162
175
  unless event_path
163
176
  @log.warn("GITHUB_EVENT_PATH env var not found")
164
177
  return nil
data/lib/version.rb CHANGED
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Octokitted
4
4
  module Version
5
- VERSION = "0.0.8"
5
+ VERSION = "1.0.0"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: octokitted
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.8
4
+ version: 1.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Grant Birkinbine