octokit 4.15.0 → 6.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +2 -4
- data/README.md +104 -80
- data/Rakefile +5 -3
- data/lib/ext/sawyer/relation.rb +4 -2
- data/lib/octokit/arguments.rb +2 -2
- data/lib/octokit/authentication.rb +12 -14
- data/lib/octokit/client/actions_artifacts.rb +71 -0
- data/lib/octokit/client/actions_secrets.rb +59 -0
- data/lib/octokit/client/actions_workflow_jobs.rb +65 -0
- data/lib/octokit/client/actions_workflow_runs.rb +125 -0
- data/lib/octokit/client/actions_workflows.rb +68 -0
- data/lib/octokit/client/apps.rb +53 -53
- data/lib/octokit/client/checks.rb +18 -29
- data/lib/octokit/client/commit_branches.rb +20 -0
- data/lib/octokit/client/commit_comments.rb +8 -8
- data/lib/octokit/client/commit_pulls.rb +2 -2
- data/lib/octokit/client/commits.rb +31 -34
- data/lib/octokit/client/community_profile.rb +2 -3
- data/lib/octokit/client/contents.rb +24 -21
- data/lib/octokit/client/deployments.rb +16 -6
- data/lib/octokit/client/downloads.rb +5 -6
- data/lib/octokit/client/emojis.rb +3 -3
- data/lib/octokit/client/events.rb +4 -4
- data/lib/octokit/client/feeds.rb +4 -5
- data/lib/octokit/client/gists.rb +6 -6
- data/lib/octokit/client/gitignore.rb +3 -3
- data/lib/octokit/client/hooks.rb +9 -19
- data/lib/octokit/client/issues.rb +14 -15
- data/lib/octokit/client/labels.rb +10 -10
- data/lib/octokit/client/legacy_search.rb +3 -3
- data/lib/octokit/client/licenses.rb +3 -6
- data/lib/octokit/client/markdown.rb +3 -3
- data/lib/octokit/client/marketplace.rb +4 -4
- data/lib/octokit/client/meta.rb +4 -5
- data/lib/octokit/client/milestones.rb +5 -5
- data/lib/octokit/client/notifications.rb +6 -6
- data/lib/octokit/client/oauth_applications.rb +116 -0
- data/lib/octokit/client/objects.rb +14 -14
- data/lib/octokit/client/organizations.rb +112 -70
- data/lib/octokit/client/pages.rb +5 -7
- data/lib/octokit/client/projects.rb +44 -64
- data/lib/octokit/client/pub_sub_hubbub.rb +16 -16
- data/lib/octokit/client/pull_requests.rb +52 -42
- data/lib/octokit/client/rate_limit.rb +9 -11
- data/lib/octokit/client/reactions.rb +6 -11
- data/lib/octokit/client/refs.rb +32 -19
- data/lib/octokit/client/releases.rb +13 -13
- data/lib/octokit/client/repositories.rb +123 -69
- data/lib/octokit/client/repository_invitations.rb +3 -3
- data/lib/octokit/client/reviews.rb +7 -7
- data/lib/octokit/client/say.rb +4 -5
- data/lib/octokit/client/search.rb +24 -11
- data/lib/octokit/client/service_status.rb +19 -9
- data/lib/octokit/client/source_import.rb +7 -12
- data/lib/octokit/client/stats.rb +10 -9
- data/lib/octokit/client/statuses.rb +5 -5
- data/lib/octokit/client/tokens.rb +31 -0
- data/lib/octokit/client/traffic.rb +6 -11
- data/lib/octokit/client/users.rb +104 -24
- data/lib/octokit/client.rb +44 -18
- data/lib/octokit/configurable.rb +34 -30
- data/lib/octokit/connection.rb +28 -26
- data/lib/octokit/default.rb +46 -35
- data/lib/octokit/enterprise_admin_client/admin_stats.rb +13 -14
- data/lib/octokit/enterprise_admin_client/license.rb +3 -4
- data/lib/octokit/enterprise_admin_client/orgs.rb +3 -4
- data/lib/octokit/enterprise_admin_client/search_indexing.rb +7 -8
- data/lib/octokit/enterprise_admin_client/users.rb +5 -4
- data/lib/octokit/enterprise_admin_client.rb +9 -3
- data/lib/octokit/enterprise_management_console_client/management_console.rb +32 -32
- data/lib/octokit/enterprise_management_console_client.rb +8 -2
- data/lib/octokit/error.rb +72 -27
- data/lib/octokit/gist.rb +2 -3
- data/lib/octokit/middleware/follow_redirects.rb +15 -11
- data/lib/octokit/organization.rb +3 -1
- data/lib/octokit/rate_limit.rb +3 -3
- data/lib/octokit/repo_arguments.rb +2 -3
- data/lib/octokit/repository.rb +24 -24
- data/lib/octokit/response/base_middleware.rb +10 -0
- data/lib/octokit/response/feed_parser.rb +5 -9
- data/lib/octokit/response/raise_error.rb +4 -6
- data/lib/octokit/user.rb +4 -2
- data/lib/octokit/version.rb +4 -2
- data/lib/octokit/warnable.rb +4 -5
- data/lib/octokit.rb +15 -8
- data/octokit.gemspec +12 -10
- metadata +25 -17
- data/lib/octokit/client/authorizations.rb +0 -250
- data/lib/octokit/preview.rb +0 -46
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: c3018cabf6ab75fe3a4340d20a4844ab92fa7059a4bbbdd96b9b671537aef5b5
|
4
|
+
data.tar.gz: 6308252f312bb301eadfe573daf9d5e17ce0698480dbdc938f72b62831e73632
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 7477cd6b438fedbec3fe952a8aebeefa224b991a65c8950c26c938db69962614d1ae066c3afd4b40a37ab935637af2dbc08ae126f8e5d199c16df1e646b2878b
|
7
|
+
data.tar.gz: 6d891d836aa8118c9cce64d265ee26d8e97f7dc05425d491d0d7123f1b9fab12eb3aa62ccc85a1b69640ed29819dba7b19d34161f2fa5b159a0b36701c0c758a
|
data/CONTRIBUTING.md
CHANGED
@@ -1,8 +1,8 @@
|
|
1
1
|
## Submitting a Pull Request
|
2
2
|
|
3
3
|
0. Read our [Code of Conduct](CODE_OF_CONDUCT.md).
|
4
|
-
1. Check out Hacking on Octokit in the
|
5
|
-
bootstrapping the project for local development.
|
4
|
+
1. Check out [Hacking on Octokit](README.md#hacking-on-octokitrb) in the
|
5
|
+
README for bootstrapping the project for local development.
|
6
6
|
2. [Fork the repository.][fork]
|
7
7
|
3. [Create a topic branch.][branch]
|
8
8
|
4. Add specs for your unimplemented feature or bug fix.
|
@@ -18,8 +18,6 @@
|
|
18
18
|
add "[ci skip]" to your commit message to avoid needless CI builds.
|
19
19
|
12. [Submit a pull request.][pr]
|
20
20
|
|
21
|
-
Please abide by
|
22
|
-
|
23
21
|
[fork]: https://help.github.com/articles/fork-a-repo
|
24
22
|
[branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
|
25
23
|
[pr]: https://help.github.com/articles/using-pull-requests
|
data/README.md
CHANGED
@@ -1,8 +1,11 @@
|
|
1
1
|
# Octokit
|
2
2
|
|
3
|
+
> **Note**
|
4
|
+
> We've recently renamed the `4-stable` branch to `main`. This might affect you if you're making changes to Octokit's code locally. For more details and for the steps to reconfigure your local clone for the new branch name, check out [this post](https://github.com/octokit/octokit.rb/discussions/1455).
|
5
|
+
|
3
6
|
Ruby toolkit for the GitHub API.
|
4
7
|
|
5
|
-
![logo](
|
8
|
+
![logo](https://docs.github.com/assets/images/gundamcat.png)
|
6
9
|
|
7
10
|
Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
|
8
11
|
[major version][semver].
|
@@ -10,23 +13,25 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
|
|
10
13
|
## Table of Contents
|
11
14
|
|
12
15
|
1. [Philosophy](#philosophy)
|
13
|
-
2. [
|
16
|
+
2. [Installation](#quick-start)
|
14
17
|
3. [Making requests](#making-requests)
|
18
|
+
1. [Additional Query Parameters](#additional-query-parameters)
|
15
19
|
4. [Consuming resources](#consuming-resources)
|
16
20
|
5. [Accessing HTTP responses](#accessing-http-responses)
|
17
|
-
6. [
|
21
|
+
6. [Handling errors](#handling-errors)
|
22
|
+
7. [Authentication](#authentication)
|
18
23
|
1. [Basic Authentication](#basic-authentication)
|
19
24
|
2. [OAuth access tokens](#oauth-access-tokens)
|
20
25
|
3. [Two-Factor Authentication](#two-factor-authentication)
|
21
26
|
4. [Using a .netrc file](#using-a-netrc-file)
|
22
27
|
5. [Application authentication](#application-authentication)
|
23
|
-
|
28
|
+
8. [Pagination](#pagination)
|
24
29
|
1. [Auto pagination](#auto-pagination)
|
25
|
-
|
30
|
+
9. [Working with GitHub Enterprise](#working-with-github-enterprise)
|
26
31
|
1. [Interacting with the GitHub.com APIs in GitHub Enterprise](#interacting-with-the-githubcom-apis-in-github-enterprise)
|
27
32
|
2. [Interacting with the GitHub Enterprise Admin APIs](#interacting-with-the-github-enterprise-admin-apis)
|
28
33
|
3. [Interacting with the GitHub Enterprise Management Console APIs](#interacting-with-the-github-enterprise-management-console-apis)
|
29
|
-
|
34
|
+
4. [SSL Connection Errors](#ssl-connection-errors)
|
30
35
|
10. [Configuration and defaults](#configuration-and-defaults)
|
31
36
|
1. [Configuring module defaults](#configuring-module-defaults)
|
32
37
|
2. [Using ENV variables](#using-env-variables)
|
@@ -41,7 +46,7 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
|
|
41
46
|
1. [Debugging](#debugging)
|
42
47
|
2. [Caching](#caching)
|
43
48
|
14. [Hacking on Octokit.rb](#hacking-on-octokitrb)
|
44
|
-
1. [Code of
|
49
|
+
1. [Code of Conduct](#code-of-conduct)
|
45
50
|
2. [Running and writing new tests](#running-and-writing-new-tests)
|
46
51
|
15. [Supported Ruby Versions](#supported-ruby-versions)
|
47
52
|
16. [Versioning](#versioning)
|
@@ -66,7 +71,7 @@ client.readme 'al3x/sovereign', :accept => 'application/vnd.github.html'
|
|
66
71
|
[wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper
|
67
72
|
[github-api]: https://developer.github.com/v3/
|
68
73
|
|
69
|
-
##
|
74
|
+
## Installation
|
70
75
|
|
71
76
|
Install via Rubygems
|
72
77
|
|
@@ -74,28 +79,28 @@ Install via Rubygems
|
|
74
79
|
|
75
80
|
... or add to your Gemfile
|
76
81
|
|
77
|
-
gem "octokit", "~>
|
82
|
+
gem "octokit", "~> 5.0"
|
78
83
|
|
79
84
|
Access the library in Ruby:
|
80
85
|
|
81
86
|
require 'octokit'
|
82
87
|
|
83
|
-
|
88
|
+
## Making requests
|
84
89
|
|
85
90
|
[API methods][] are available as client instance methods.
|
86
91
|
|
87
92
|
```ruby
|
88
93
|
# Provide authentication credentials
|
89
|
-
client = Octokit::Client.new(:
|
94
|
+
client = Octokit::Client.new(:access_token => 'personal_access_token')
|
90
95
|
|
91
|
-
#
|
92
|
-
# client = Octokit::Client.new(:
|
96
|
+
# You can still use the username/password syntax by replacing the password value with your PAT.
|
97
|
+
# client = Octokit::Client.new(:login => 'defunkt', :password => 'personal_access_token')
|
93
98
|
|
94
99
|
# Fetch the current user
|
95
100
|
client.user
|
96
101
|
```
|
97
102
|
|
98
|
-
### Additional
|
103
|
+
### Additional query parameters
|
99
104
|
|
100
105
|
When passing additional parameters to GET based request use the following syntax:
|
101
106
|
|
@@ -109,9 +114,9 @@ When passing additional parameters to GET based request use the following syntax
|
|
109
114
|
client.contents('octokit/octokit.rb', path: 'path/to/file.rb', query: {ref: 'some-other-branch'})
|
110
115
|
```
|
111
116
|
|
112
|
-
[
|
117
|
+
[api methods]: http://octokit.github.io/octokit.rb/method_list.html
|
113
118
|
|
114
|
-
|
119
|
+
## Consuming resources
|
115
120
|
|
116
121
|
Most methods return a `Resource` object which provides dot notation and `[]`
|
117
122
|
access for fields returned in the API response.
|
@@ -134,7 +139,7 @@ user.rels[:gists].href
|
|
134
139
|
**Note:** URL fields are culled into a separate `.rels` collection for easier
|
135
140
|
[Hypermedia](#hypermedia-agent) support.
|
136
141
|
|
137
|
-
|
142
|
+
## Accessing HTTP responses
|
138
143
|
|
139
144
|
While most methods return a `Resource` object or a Boolean, sometimes you may
|
140
145
|
need access to the raw HTTP response headers. You can access the last HTTP
|
@@ -146,6 +151,23 @@ response = client.last_response
|
|
146
151
|
etag = response.headers[:etag]
|
147
152
|
```
|
148
153
|
|
154
|
+
## Handling errors
|
155
|
+
|
156
|
+
When the API returns an error response, Octokit will raise a Ruby exception.
|
157
|
+
|
158
|
+
A range of different exceptions can be raised depending on the error returned
|
159
|
+
by the API - for example:
|
160
|
+
|
161
|
+
* A `400 Bad Request` response will lead to an `Octokit::BadRequest` error
|
162
|
+
* A `403 Forbidden` error with a "rate limited exceeded" message will lead
|
163
|
+
to a `Octokit::TooManyRequests` error
|
164
|
+
|
165
|
+
All of the different exception classes inherit from `Octokit::Error` and
|
166
|
+
expose the `#response_status`, `#response_headers` and `#response_body`.
|
167
|
+
For validation errors, `#errors` will return an `Array` of `Hash`es
|
168
|
+
with the detailed information
|
169
|
+
[returned by the API](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#client-errors).
|
170
|
+
|
149
171
|
## Authentication
|
150
172
|
|
151
173
|
Octokit supports the various [authentication methods supported by the GitHub
|
@@ -163,6 +185,7 @@ user = client.user
|
|
163
185
|
user.login
|
164
186
|
# => "defunkt"
|
165
187
|
```
|
188
|
+
|
166
189
|
While Basic Authentication allows you to get started quickly, OAuth access
|
167
190
|
tokens are the preferred way to authenticate on behalf of users.
|
168
191
|
|
@@ -171,9 +194,9 @@ tokens are the preferred way to authenticate on behalf of users.
|
|
171
194
|
[OAuth access tokens][oauth] provide two main benefits over using your username
|
172
195
|
and password:
|
173
196
|
|
174
|
-
|
197
|
+
- **Revocable access**. Access tokens can be revoked, removing access for only
|
175
198
|
that token without having to change your password everywhere.
|
176
|
-
|
199
|
+
- **Limited access**. Access tokens have [access scopes][] which allow for more
|
177
200
|
granular access to API resources. For instance, you can grant a third party
|
178
201
|
access to your gists but not your private repositories.
|
179
202
|
|
@@ -212,7 +235,7 @@ client = Octokit::Client.new \
|
|
212
235
|
user = client.user("defunkt", :headers => { "X-GitHub-OTP" => "<your 2FA token>" })
|
213
236
|
```
|
214
237
|
|
215
|
-
As you can imagine, this gets annoying
|
238
|
+
As you can imagine, this gets annoying quickly since two-factor auth tokens are very short lived. So it is recommended to create an oauth token for the user to communicate with the API:
|
216
239
|
|
217
240
|
```ruby
|
218
241
|
client = Octokit::Client.new \
|
@@ -227,13 +250,14 @@ client.create_authorization(:scopes => ["user"], :note => "Name of token",
|
|
227
250
|
### Using a .netrc file
|
228
251
|
|
229
252
|
Octokit supports reading credentials from a netrc file (defaulting to
|
230
|
-
`~/.netrc`).
|
253
|
+
`~/.netrc`). Given these lines in your netrc:
|
231
254
|
|
232
255
|
```
|
233
256
|
machine api.github.com
|
234
257
|
login defunkt
|
235
258
|
password c0d3b4ssssss!
|
236
259
|
```
|
260
|
+
|
237
261
|
You can now create a client with those credentials:
|
238
262
|
|
239
263
|
```ruby
|
@@ -241,6 +265,7 @@ client = Octokit::Client.new(:netrc => true)
|
|
241
265
|
client.login
|
242
266
|
# => "defunkt"
|
243
267
|
```
|
268
|
+
|
244
269
|
But _I want to use OAuth_ you say. Since the GitHub API supports using an OAuth
|
245
270
|
token as a Basic password, you totally can:
|
246
271
|
|
@@ -323,13 +348,13 @@ custom pattern for traversing large lists.
|
|
323
348
|
|
324
349
|
## Working with GitHub Enterprise
|
325
350
|
|
326
|
-
With a bit of setup, you can also use Octokit with your
|
351
|
+
With a bit of setup, you can also use Octokit with your GitHub Enterprise instance.
|
327
352
|
|
328
353
|
### Interacting with the GitHub.com APIs in GitHub Enterprise
|
329
354
|
|
330
355
|
To interact with the "regular" GitHub.com APIs in GitHub Enterprise, simply configure the `api_endpoint` to match your hostname. For example:
|
331
356
|
|
332
|
-
```
|
357
|
+
```ruby
|
333
358
|
Octokit.configure do |c|
|
334
359
|
c.api_endpoint = "https://<hostname>/api/v3/"
|
335
360
|
end
|
@@ -341,7 +366,7 @@ client = Octokit::Client.new(:access_token => "<your 40 char token>")
|
|
341
366
|
|
342
367
|
The GitHub Enterprise Admin APIs are under a different client: `EnterpriseAdminClient`. You'll need to have an administrator account in order to use these APIs.
|
343
368
|
|
344
|
-
```
|
369
|
+
```ruby
|
345
370
|
admin_client = Octokit::EnterpriseAdminClient.new(
|
346
371
|
:access_token => "<your 40 char token>",
|
347
372
|
:api_endpoint => "https://<hostname>/api/v3/"
|
@@ -358,9 +383,9 @@ admin_client = Octokit.enterprise_admin_client.new
|
|
358
383
|
|
359
384
|
### Interacting with the GitHub Enterprise Management Console APIs
|
360
385
|
|
361
|
-
The GitHub Enterprise Management Console APIs are also under a separate client: `EnterpriseManagementConsoleClient`. In order to use it, you'll need to provide both your management console password as well as the endpoint to your management console. This is different
|
386
|
+
The GitHub Enterprise Management Console APIs are also under a separate client: `EnterpriseManagementConsoleClient`. In order to use it, you'll need to provide both your management console password as well as the endpoint to your management console. This is different from the API endpoint provided above.
|
362
387
|
|
363
|
-
```
|
388
|
+
```ruby
|
364
389
|
management_console_client = Octokit::EnterpriseManagementConsoleClient.new(
|
365
390
|
:management_console_password => "secret",
|
366
391
|
:management_console_endpoint = "https://hostname:8633"
|
@@ -377,9 +402,9 @@ management_console_client = Octokit.enterprise_management_console_client.new
|
|
377
402
|
|
378
403
|
### SSL Connection Errors
|
379
404
|
|
380
|
-
You
|
405
|
+
You _may_ need to disable SSL temporarily while first setting up your GitHub Enterprise install. You can do that with the following configuration:
|
381
406
|
|
382
|
-
```
|
407
|
+
```ruby
|
383
408
|
client.connection_options[:ssl] = { :verify => false }
|
384
409
|
```
|
385
410
|
|
@@ -444,6 +469,7 @@ Octokit.configure do |c|
|
|
444
469
|
}
|
445
470
|
end
|
446
471
|
```
|
472
|
+
|
447
473
|
You should set a timeout in order to avoid Ruby’s Timeout module, which can hose your server. Here are some resources for more information on this:
|
448
474
|
|
449
475
|
- [The Oldest Bug In Ruby - Why Rack::Timeout Might Hose your Server](https://www.schneems.com/2017/02/21/the-oldest-bug-in-ruby-why-racktimeout-might-hose-your-server/)
|
@@ -473,7 +499,7 @@ repos.last.name
|
|
473
499
|
# => "faraday-zeromq"
|
474
500
|
```
|
475
501
|
|
476
|
-
When processing API responses, all `*_url` attributes are culled
|
502
|
+
When processing API responses, all `*_url` attributes are culled into the link
|
477
503
|
relations collection. Any `url` attribute becomes `.rels[:self]`.
|
478
504
|
|
479
505
|
### URI templates
|
@@ -509,8 +535,8 @@ Octokit 3.0 aims to be hypermedia-driven, removing the internal URL
|
|
509
535
|
construction currently used throughout the client.
|
510
536
|
|
511
537
|
[hypermedia]: http://en.wikipedia.org/wiki/Hypermedia
|
512
|
-
[
|
513
|
-
[
|
538
|
+
[sawyer]: https://github.com/lostisland/sawyer
|
539
|
+
[faraday]: https://github.com/lostisland/faraday
|
514
540
|
[uri-templates]: http://tools.ietf.org/html/rfc6570
|
515
541
|
|
516
542
|
## Upgrading guide
|
@@ -518,8 +544,8 @@ construction currently used throughout the client.
|
|
518
544
|
Version 4.0
|
519
545
|
|
520
546
|
- **removes support for a [long-deprecated overload][list-pulls] for
|
521
|
-
passing state as a positional argument** when listing pull requests. Instead,
|
522
|
-
pass `state` in the method options.
|
547
|
+
passing state as a positional argument** when listing pull requests. Instead,
|
548
|
+
pass `state` in the method options.
|
523
549
|
- **drops support for Ruby < 2.0**.
|
524
550
|
- adds support for new [Enterprise-only APIs](#working-with-github-enterprise).
|
525
551
|
- adds support for [Repository redirects][redirects].
|
@@ -536,6 +562,7 @@ for the client:
|
|
536
562
|
```ruby
|
537
563
|
Octokit.default_media_type = "application/vnd.github.beta+json"
|
538
564
|
```
|
565
|
+
|
539
566
|
or per-request
|
540
567
|
|
541
568
|
```ruby
|
@@ -552,21 +579,20 @@ Version 2.0 includes a completely rewritten `Client` factory that now memoizes
|
|
552
579
|
client instances based on unique configuration options. Breaking changes also
|
553
580
|
include:
|
554
581
|
|
555
|
-
|
556
|
-
|
557
|
-
|
582
|
+
- `:oauth_token` is now `:access_token`
|
583
|
+
- `:auto_traversal` is now `:auto_paginate`
|
584
|
+
- `Hashie::Mash` has been removed. Responses now return a `Sawyer::Resource`
|
558
585
|
object. This new type behaves mostly like a Ruby `Hash`, but does not fully
|
559
586
|
support the `Hashie::Mash` API.
|
560
|
-
|
587
|
+
- Two new client error types are raised where appropriate:
|
561
588
|
`Octokit::TooManyRequests` and `Octokit::TooManyLoginAttempts`
|
562
|
-
|
563
|
-
|
589
|
+
- The `search_*` methods from v1.x are now found at `legacy_search_*`
|
590
|
+
- Support for netrc requires including the [netrc gem][] in your Gemfile or
|
564
591
|
gemspec.
|
565
|
-
|
592
|
+
- DateTime fields are now proper `DateTime` objects. Previous versions outputted DateTime fields as 'String' objects.
|
566
593
|
|
567
594
|
[netrc gem]: https://rubygems.org/gems/netrc
|
568
595
|
|
569
|
-
|
570
596
|
## Advanced usage
|
571
597
|
|
572
598
|
Since Octokit employs [Faraday][faraday] under the hood, some behavior can be
|
@@ -580,11 +606,13 @@ traffic:
|
|
580
606
|
|
581
607
|
```ruby
|
582
608
|
stack = Faraday::RackBuilder.new do |builder|
|
583
|
-
builder.use Faraday::
|
609
|
+
builder.use Faraday::Retry::Middleware, exceptions: [Octokit::ServerError] # or Faraday::Request::Retry for Faraday < 2.0
|
584
610
|
builder.use Octokit::Middleware::FollowRedirects
|
585
611
|
builder.use Octokit::Response::RaiseError
|
586
612
|
builder.use Octokit::Response::FeedParser
|
587
|
-
builder.response :logger
|
613
|
+
builder.response :logger do |logger|
|
614
|
+
logger.filter(/(Authorization: "(token|Bearer) )(\w+)/, '\1[REMOVED]')
|
615
|
+
end
|
588
616
|
builder.adapter Faraday.default_adapter
|
589
617
|
end
|
590
618
|
Octokit.middleware = stack
|
@@ -592,6 +620,7 @@ Octokit.middleware = stack
|
|
592
620
|
client = Octokit::Client.new
|
593
621
|
client.user 'pengwynn'
|
594
622
|
```
|
623
|
+
|
595
624
|
```
|
596
625
|
I, [2013-08-22T15:54:38.583300 #88227] INFO -- : get https://api.github.com/users/pengwynn
|
597
626
|
D, [2013-08-22T15:54:38.583401 #88227] DEBUG -- request: Accept: "application/vnd.github.beta+json"
|
@@ -635,8 +664,7 @@ Once configured, the middleware will store responses in cache based on ETag
|
|
635
664
|
fingerprint and serve those back up for future `304` responses for the same
|
636
665
|
resource. See the [project README][cache] for advanced usage.
|
637
666
|
|
638
|
-
|
639
|
-
[cache]: https://github.com/plataformatec/faraday-http-cache
|
667
|
+
[cache]: https://github.com/sourcelevel/faraday-http-cache
|
640
668
|
[faraday]: https://github.com/lostisland/faraday
|
641
669
|
|
642
670
|
## Hacking on Octokit.rb
|
@@ -651,12 +679,11 @@ to run a Ruby console to poke on Octokit, you can crank one up with:
|
|
651
679
|
|
652
680
|
script/console
|
653
681
|
|
654
|
-
Using the scripts in `./
|
655
|
-
console`, etc. ensures your dependencies are up-to-date.
|
682
|
+
Using the scripts in `./script` instead of `bundle exec rspec`, `bundle console`, etc. ensures your dependencies are up-to-date.
|
656
683
|
|
657
684
|
### Code of Conduct
|
658
685
|
|
659
|
-
We want both the Octokit.rb and larger Octokit communities to be
|
686
|
+
We want both the Octokit.rb and larger Octokit communities to be open
|
660
687
|
and welcoming environments. Please read and follow both in spirit and
|
661
688
|
letter [Code of Conduct](CODE_OF_CONDUCT.md).
|
662
689
|
|
@@ -673,56 +700,52 @@ Octokit uses environmental variables for storing credentials used in testing.
|
|
673
700
|
If you are testing an API endpoint that doesn't require authentication, you
|
674
701
|
can get away without any additional configuration. For the most part, tests
|
675
702
|
use an authenticated client, using a token stored in `ENV['OCTOKIT_TEST_GITHUB_TOKEN']`.
|
676
|
-
There are several different
|
703
|
+
There are several different authentication methods used across the api.
|
677
704
|
Here is the full list of configurable environmental variables for testing
|
678
705
|
Octokit:
|
679
706
|
|
680
|
-
ENV Variable
|
681
|
-
|
682
|
-
`OCTOKIT_TEST_GITHUB_LOGIN
|
683
|
-
`OCTOKIT_TEST_GITHUB_PASSWORD
|
684
|
-
`OCTOKIT_TEST_GITHUB_TOKEN`
|
685
|
-
`OCTOKIT_TEST_GITHUB_CLIENT_ID`
|
686
|
-
`OCTOKIT_TEST_GITHUB_CLIENT_SECRET`
|
687
|
-
`OCTOKIT_TEST_GITHUB_REPOSITORY`
|
688
|
-
`OCTOKIT_TEST_GITHUB_ORGANIZATION`
|
689
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN`
|
690
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN`
|
691
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password.
|
692
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT`
|
693
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint.
|
694
|
-
`OCTOKIT_TEST_GITHUB_INTEGRATION`
|
695
|
-
`OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION`
|
696
|
-
`OCTOKIT_TEST_INTEGRATION_PEM_KEY`
|
707
|
+
| ENV Variable | Description |
|
708
|
+
| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
709
|
+
| `OCTOKIT_TEST_GITHUB_LOGIN` | GitHub login name (preferably one created specifically for testing against). |
|
710
|
+
| `OCTOKIT_TEST_GITHUB_PASSWORD` | Password for the test GitHub login. |
|
711
|
+
| `OCTOKIT_TEST_GITHUB_TOKEN` | [Personal Access Token](https://github.com/blog/1509-personal-api-tokens) for the test GitHub login. |
|
712
|
+
| `OCTOKIT_TEST_GITHUB_CLIENT_ID` | Test OAuth application client id. |
|
713
|
+
| `OCTOKIT_TEST_GITHUB_CLIENT_SECRET` | Test OAuth application client secret. |
|
714
|
+
| `OCTOKIT_TEST_GITHUB_REPOSITORY` | Test repository to perform destructive actions against, this should not be set to any repository of importance. **Automatically created by the test suite if nonexistent** Default: `api-sandbox` |
|
715
|
+
| `OCTOKIT_TEST_GITHUB_ORGANIZATION` | Test organization. |
|
716
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN` | GitHub Enterprise login name. |
|
717
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN` | GitHub Enterprise token. |
|
718
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password. |
|
719
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT` | GitHub Enterprise hostname. |
|
720
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint. |
|
721
|
+
| `OCTOKIT_TEST_GITHUB_INTEGRATION` | [GitHub Integration](https://developer.github.com/early-access/integrations/) owned by your test organization. |
|
722
|
+
| `OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION` | Installation of the GitHub Integration specified above. |
|
723
|
+
| `OCTOKIT_TEST_INTEGRATION_PEM_KEY` | File path to the private key generated from your integration. |
|
697
724
|
|
698
725
|
Since we periodically refresh our cassettes, please keep some points in mind
|
699
726
|
when writing new specs.
|
700
727
|
|
701
|
-
|
728
|
+
- **Specs should be idempotent**. The HTTP calls made during a spec should be
|
702
729
|
able to be run over and over. This means deleting a known resource prior to
|
703
730
|
creating it if the name has to be unique.
|
704
|
-
|
731
|
+
- **Specs should be able to be run in random order.** If a spec depends on
|
705
732
|
another resource as a fixture, make sure that's created in the scope of the
|
706
733
|
spec and not depend on a previous spec to create the data needed.
|
707
|
-
|
734
|
+
- **Do not depend on authenticated user info.** Instead of asserting
|
708
735
|
actual values in resources, try to assert the existence of a key or that a
|
709
736
|
response is an Array. We're testing the client, not the API.
|
710
737
|
|
711
738
|
[bootstrapping]: http://wynnnetherland.com/linked/2013012801/bootstrapping-consistency
|
712
|
-
[
|
739
|
+
[vcr]: https://github.com/vcr/vcr
|
713
740
|
|
714
741
|
## Supported Ruby Versions
|
715
742
|
|
716
|
-
This library aims to support and is [tested against][
|
743
|
+
This library aims to support and is [tested against][actions] the following Ruby
|
717
744
|
implementations:
|
718
745
|
|
719
|
-
* Ruby 2.
|
720
|
-
* Ruby
|
721
|
-
* Ruby
|
722
|
-
* Ruby 2.3
|
723
|
-
* Ruby 2.4
|
724
|
-
* Ruby 2.5
|
725
|
-
* Ruby 2.6
|
746
|
+
* Ruby 2.7
|
747
|
+
* Ruby 3.0
|
748
|
+
* Ruby 3.1
|
726
749
|
|
727
750
|
If something doesn't work on one of these Ruby versions, it's a bug.
|
728
751
|
|
@@ -737,7 +760,7 @@ implementation, you will be responsible for providing patches in a timely
|
|
737
760
|
fashion. If critical issues for a particular implementation exist at the time
|
738
761
|
of a major release, support for that Ruby version may be dropped.
|
739
762
|
|
740
|
-
[
|
763
|
+
[actions]: https://github.com/octokit/octokit.rb/actions
|
741
764
|
|
742
765
|
## Versioning
|
743
766
|
|
@@ -759,7 +782,8 @@ The changes made between versions can be seen on the [project releases page][rel
|
|
759
782
|
[releases]: https://github.com/octokit/octokit.rb/releases
|
760
783
|
|
761
784
|
## Making Repeating Requests
|
762
|
-
|
785
|
+
|
786
|
+
In most cases it would be best to use [webhooks](https://developer.github.com/webhooks/), but sometimes webhooks don't provide all of the information needed. In those cases where one might need to poll for progress or retry a request on failure, we designed [Octopoller](https://github.com/octokit/octopoller.rb). Octopoller is a micro gem perfect for making repeating requests.
|
763
787
|
|
764
788
|
```ruby
|
765
789
|
Octopoller.poll(timeout: 15.seconds) do
|
data/Rakefile
CHANGED
@@ -1,11 +1,13 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
1
3
|
require 'bundler'
|
2
4
|
Bundler::GemHelper.install_tasks
|
3
5
|
|
4
6
|
require 'rspec/core/rake_task'
|
5
7
|
RSpec::Core::RakeTask.new(:spec)
|
6
8
|
|
7
|
-
task :
|
8
|
-
task :
|
9
|
+
task test: :spec
|
10
|
+
task default: :spec
|
9
11
|
|
10
12
|
namespace :doc do
|
11
13
|
begin
|
@@ -14,7 +16,7 @@ namespace :doc do
|
|
14
16
|
task.files = ['README.md', 'LICENSE.md', 'lib/**/*.rb']
|
15
17
|
task.options = [
|
16
18
|
'--output-dir', 'doc/yard',
|
17
|
-
'--markup', 'markdown'
|
19
|
+
'--markup', 'markdown'
|
18
20
|
]
|
19
21
|
end
|
20
22
|
rescue LoadError
|
data/lib/ext/sawyer/relation.rb
CHANGED
@@ -1,9 +1,11 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
1
3
|
require 'sawyer'
|
2
4
|
|
3
5
|
patch = Module.new do
|
4
|
-
def href(options=nil)
|
6
|
+
def href(options = nil)
|
5
7
|
# Temporary workaround for: https://github.com/octokit/octokit.rb/issues/727
|
6
|
-
name.to_s ==
|
8
|
+
name.to_s == 'ssh' ? @href : super
|
7
9
|
end
|
8
10
|
end
|
9
11
|
|
data/lib/octokit/arguments.rb
CHANGED
@@ -1,5 +1,6 @@
|
|
1
|
-
|
1
|
+
# frozen_string_literal: true
|
2
2
|
|
3
|
+
module Octokit
|
3
4
|
# Extracts options from method arguments
|
4
5
|
# @private
|
5
6
|
class Arguments < Array
|
@@ -9,6 +10,5 @@ module Octokit
|
|
9
10
|
@options = args.last.is_a?(::Hash) ? args.pop : {}
|
10
11
|
super(args)
|
11
12
|
end
|
12
|
-
|
13
13
|
end
|
14
14
|
end
|
@@ -1,7 +1,15 @@
|
|
1
|
-
|
1
|
+
# frozen_string_literal: true
|
2
2
|
|
3
|
+
module Octokit
|
3
4
|
# Authentication methods for {Octokit::Client}
|
4
5
|
module Authentication
|
6
|
+
# In Faraday 2.x, the authorization middleware uses new interface
|
7
|
+
FARADAY_BASIC_AUTH_KEYS =
|
8
|
+
if Gem::Version.new(Faraday::VERSION) >= Gem::Version.new('2.0')
|
9
|
+
%i[authorization basic]
|
10
|
+
else
|
11
|
+
[:basic_auth]
|
12
|
+
end
|
5
13
|
|
6
14
|
# Indicates if the client was supplied Basic Auth
|
7
15
|
# username and password
|
@@ -43,22 +51,13 @@ module Octokit
|
|
43
51
|
# requests at a higher rate limit
|
44
52
|
#
|
45
53
|
# @see https://developer.github.com/v3/#unauthenticated-rate-limited-requests
|
46
|
-
# @return Boolean
|
54
|
+
# @return [Boolean]
|
47
55
|
def application_authenticated?
|
48
|
-
!!
|
56
|
+
!!(@client_id && @client_secret)
|
49
57
|
end
|
50
58
|
|
51
59
|
private
|
52
60
|
|
53
|
-
def application_authentication
|
54
|
-
if @client_id && @client_secret
|
55
|
-
{
|
56
|
-
:client_id => @client_id,
|
57
|
-
:client_secret => @client_secret
|
58
|
-
}
|
59
|
-
end
|
60
|
-
end
|
61
|
-
|
62
61
|
def login_from_netrc
|
63
62
|
return unless netrc?
|
64
63
|
|
@@ -75,8 +74,7 @@ module Octokit
|
|
75
74
|
self.password = creds.shift
|
76
75
|
end
|
77
76
|
rescue LoadError
|
78
|
-
octokit_warn
|
77
|
+
octokit_warn 'Please install netrc gem for .netrc support'
|
79
78
|
end
|
80
|
-
|
81
79
|
end
|
82
80
|
end
|