octokit 4.6.2 → 6.1.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/CONTRIBUTING.md +14 -13
- data/LICENSE.md +1 -1
- data/README.md +239 -118
- data/Rakefile +12 -12
- data/lib/ext/sawyer/relation.rb +4 -2
- data/lib/octokit/arguments.rb +2 -2
- data/lib/octokit/authentication.rb +20 -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 +222 -0
- data/lib/octokit/client/checks.rb +200 -0
- 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 +20 -0
- data/lib/octokit/client/commits.rb +31 -34
- data/lib/octokit/client/community_profile.rb +21 -0
- data/lib/octokit/client/contents.rb +25 -20
- data/lib/octokit/client/deployments.rb +25 -5
- data/lib/octokit/client/downloads.rb +5 -6
- data/lib/octokit/client/emojis.rb +3 -3
- data/lib/octokit/client/environments.rb +55 -0
- data/lib/octokit/client/events.rb +4 -4
- data/lib/octokit/client/feeds.rb +4 -5
- data/lib/octokit/client/gists.rb +7 -6
- data/lib/octokit/client/gitignore.rb +3 -3
- data/lib/octokit/client/hooks.rb +9 -19
- data/lib/octokit/client/issues.rb +60 -14
- data/lib/octokit/client/labels.rb +17 -17
- data/lib/octokit/client/legacy_search.rb +3 -3
- data/lib/octokit/client/licenses.rb +4 -7
- data/lib/octokit/client/markdown.rb +3 -3
- data/lib/octokit/client/marketplace.rb +56 -0
- data/lib/octokit/client/meta.rb +4 -5
- data/lib/octokit/client/milestones.rb +5 -5
- data/lib/octokit/client/notifications.rb +6 -10
- data/lib/octokit/client/oauth_applications.rb +116 -0
- data/lib/octokit/client/objects.rb +14 -14
- data/lib/octokit/client/organizations.rb +238 -61
- data/lib/octokit/client/pages.rb +5 -7
- data/lib/octokit/client/projects.rb +50 -70
- data/lib/octokit/client/pub_sub_hubbub.rb +16 -16
- data/lib/octokit/client/pull_requests.rb +58 -46
- data/lib/octokit/client/rate_limit.rb +11 -13
- data/lib/octokit/client/reactions.rb +6 -11
- data/lib/octokit/client/refs.rb +32 -19
- data/lib/octokit/client/releases.rb +14 -13
- data/lib/octokit/client/repositories.rb +195 -54
- data/lib/octokit/client/repository_invitations.rb +4 -11
- data/lib/octokit/client/reviews.rb +227 -0
- data/lib/octokit/client/say.rb +4 -5
- data/lib/octokit/client/search.rb +46 -17
- data/lib/octokit/client/service_status.rb +19 -9
- data/lib/octokit/client/source_import.rb +8 -13
- data/lib/octokit/client/stats.rb +12 -9
- data/lib/octokit/client/statuses.rb +6 -6
- data/lib/octokit/client/tokens.rb +31 -0
- data/lib/octokit/client/traffic.rb +6 -11
- data/lib/octokit/client/users.rb +106 -25
- data/lib/octokit/client.rb +66 -17
- data/lib/octokit/configurable.rb +42 -30
- data/lib/octokit/connection.rb +43 -21
- data/lib/octokit/default.rb +63 -34
- data/lib/octokit/enterprise_admin_client/admin_stats.rb +14 -15
- data/lib/octokit/enterprise_admin_client/license.rb +4 -5
- data/lib/octokit/enterprise_admin_client/orgs.rb +5 -6
- data/lib/octokit/enterprise_admin_client/search_indexing.rb +8 -9
- data/lib/octokit/enterprise_admin_client/users.rb +17 -16
- data/lib/octokit/enterprise_admin_client.rb +9 -3
- data/lib/octokit/enterprise_management_console_client/management_console.rb +33 -33
- data/lib/octokit/enterprise_management_console_client.rb +9 -3
- data/lib/octokit/error.rb +107 -26
- data/lib/octokit/gist.rb +4 -5
- data/lib/octokit/middleware/follow_redirects.rb +17 -13
- data/lib/octokit/organization.rb +3 -1
- data/lib/octokit/rate_limit.rb +11 -9
- data/lib/octokit/repo_arguments.rb +2 -3
- data/lib/octokit/repository.rb +27 -25
- 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 +5 -3
- data/lib/octokit/warnable.rb +4 -5
- data/lib/octokit.rb +15 -8
- data/octokit.gemspec +13 -10
- metadata +55 -22
- data/lib/octokit/client/authorizations.rb +0 -244
- data/lib/octokit/preview.rb +0 -35
data/README.md
CHANGED
@@ -1,9 +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
|
-
![
|
6
|
-
[logo]: http://cl.ly/image/3Y013H0A2z3z/gundam-ruby.png
|
8
|
+
![logo](https://docs.github.com/assets/images/gundamcat.png)
|
7
9
|
|
8
10
|
Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
|
9
11
|
[major version][semver].
|
@@ -11,40 +13,47 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
|
|
11
13
|
## Table of Contents
|
12
14
|
|
13
15
|
1. [Philosophy](#philosophy)
|
14
|
-
2. [
|
16
|
+
2. [Installation](#installation)
|
15
17
|
3. [Making requests](#making-requests)
|
18
|
+
1. [Additional Query Parameters](#additional-query-parameters)
|
16
19
|
4. [Consuming resources](#consuming-resources)
|
17
20
|
5. [Accessing HTTP responses](#accessing-http-responses)
|
18
|
-
6. [
|
21
|
+
6. [Handling errors](#handling-errors)
|
22
|
+
7. [Authentication](#authentication)
|
19
23
|
1. [Basic Authentication](#basic-authentication)
|
20
24
|
2. [OAuth access tokens](#oauth-access-tokens)
|
21
25
|
3. [Two-Factor Authentication](#two-factor-authentication)
|
22
26
|
4. [Using a .netrc file](#using-a-netrc-file)
|
23
27
|
5. [Application authentication](#application-authentication)
|
24
|
-
|
28
|
+
6. [GitHub App](#github-app)
|
29
|
+
8. [Default results per_page](#default-results-per_page)
|
30
|
+
9. [Pagination](#pagination)
|
25
31
|
1. [Auto pagination](#auto-pagination)
|
26
|
-
|
32
|
+
10. [Working with GitHub Enterprise](#working-with-github-enterprise)
|
27
33
|
1. [Interacting with the GitHub.com APIs in GitHub Enterprise](#interacting-with-the-githubcom-apis-in-github-enterprise)
|
28
34
|
2. [Interacting with the GitHub Enterprise Admin APIs](#interacting-with-the-github-enterprise-admin-apis)
|
29
35
|
3. [Interacting with the GitHub Enterprise Management Console APIs](#interacting-with-the-github-enterprise-management-console-apis)
|
30
|
-
|
31
|
-
|
36
|
+
4. [SSL Connection Errors](#ssl-connection-errors)
|
37
|
+
11. [Configuration and defaults](#configuration-and-defaults)
|
32
38
|
1. [Configuring module defaults](#configuring-module-defaults)
|
33
39
|
2. [Using ENV variables](#using-env-variables)
|
34
|
-
|
40
|
+
3. [Timeouts](#timeouts)
|
41
|
+
12. [Hypermedia agent](#hypermedia-agent)
|
35
42
|
1. [Hypermedia in Octokit](#hypermedia-in-octokit)
|
36
43
|
2. [URI templates](#uri-templates)
|
37
44
|
3. [The Full Hypermedia Experience™](#the-full-hypermedia-experience)
|
38
|
-
|
45
|
+
13. [Upgrading guide](#upgrading-guide)
|
39
46
|
1. [Upgrading from 1.x.x](#upgrading-from-1xx)
|
40
|
-
|
47
|
+
14. [Advanced usage](#advanced-usage)
|
41
48
|
1. [Debugging](#debugging)
|
42
49
|
2. [Caching](#caching)
|
43
|
-
|
44
|
-
1. [
|
45
|
-
|
46
|
-
16. [
|
47
|
-
17. [
|
50
|
+
15. [Hacking on Octokit.rb](#hacking-on-octokitrb)
|
51
|
+
1. [Code of Conduct](#code-of-conduct)
|
52
|
+
2. [Running and writing new tests](#running-and-writing-new-tests)
|
53
|
+
16. [Supported Ruby Versions](#supported-ruby-versions)
|
54
|
+
17. [Versioning](#versioning)
|
55
|
+
18. [Making Repeating Requests](#making-repeating-requests)
|
56
|
+
19. [License](#license)
|
48
57
|
|
49
58
|
## Philosophy
|
50
59
|
|
@@ -55,15 +64,16 @@ Most methods have positional arguments for required input and an options hash
|
|
55
64
|
for optional parameters, headers, or other options:
|
56
65
|
|
57
66
|
```ruby
|
67
|
+
client = Octokit::Client.new
|
68
|
+
|
58
69
|
# Fetch a README with Accept header for HTML format
|
59
|
-
|
70
|
+
client.readme 'al3x/sovereign', :accept => 'application/vnd.github.html'
|
60
71
|
```
|
61
72
|
|
62
|
-
|
63
73
|
[wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper
|
64
|
-
[github-api]:
|
74
|
+
[github-api]: https://developer.github.com/v3/
|
65
75
|
|
66
|
-
##
|
76
|
+
## Installation
|
67
77
|
|
68
78
|
Install via Rubygems
|
69
79
|
|
@@ -71,42 +81,53 @@ Install via Rubygems
|
|
71
81
|
|
72
82
|
... or add to your Gemfile
|
73
83
|
|
74
|
-
gem "octokit", "~>
|
84
|
+
gem "octokit", "~> 5.0"
|
85
|
+
|
86
|
+
Access the library in Ruby:
|
87
|
+
|
88
|
+
require 'octokit'
|
75
89
|
|
76
|
-
|
90
|
+
## Making requests
|
77
91
|
|
78
|
-
[API methods][] are available as
|
79
|
-
configuration) or as client instance methods.
|
92
|
+
[API methods][] are available as client instance methods.
|
80
93
|
|
81
94
|
```ruby
|
82
95
|
# Provide authentication credentials
|
83
|
-
Octokit.
|
84
|
-
|
85
|
-
|
86
|
-
|
96
|
+
client = Octokit::Client.new(:access_token => 'personal_access_token')
|
97
|
+
|
98
|
+
# You can still use the username/password syntax by replacing the password value with your PAT.
|
99
|
+
# client = Octokit::Client.new(:login => 'defunkt', :password => 'personal_access_token')
|
87
100
|
|
88
101
|
# Fetch the current user
|
89
|
-
|
102
|
+
client.user
|
90
103
|
```
|
91
|
-
|
104
|
+
|
105
|
+
### Additional query parameters
|
106
|
+
|
107
|
+
When passing additional parameters to GET based request use the following syntax:
|
92
108
|
|
93
109
|
```ruby
|
94
|
-
#
|
95
|
-
|
96
|
-
|
97
|
-
|
110
|
+
# query: { parameter_name: 'value' }
|
111
|
+
# Example: Get repository listing by owner in ascending order
|
112
|
+
client.repos({}, query: {type: 'owner', sort: 'asc'})
|
113
|
+
|
114
|
+
# Example: Get contents of a repository by ref
|
115
|
+
# https://api.github.com/repos/octokit/octokit.rb/contents/path/to/file.rb?ref=some-other-branch
|
116
|
+
client.contents('octokit/octokit.rb', path: 'path/to/file.rb', query: {ref: 'some-other-branch'})
|
98
117
|
```
|
99
118
|
|
100
|
-
[
|
119
|
+
[api methods]: http://octokit.github.io/octokit.rb/method_list.html
|
101
120
|
|
102
|
-
|
121
|
+
## Consuming resources
|
103
122
|
|
104
123
|
Most methods return a `Resource` object which provides dot notation and `[]`
|
105
124
|
access for fields returned in the API response.
|
106
125
|
|
107
126
|
```ruby
|
127
|
+
client = Octokit::Client.new
|
128
|
+
|
108
129
|
# Fetch a user
|
109
|
-
user =
|
130
|
+
user = client.user 'jbarnette'
|
110
131
|
puts user.name
|
111
132
|
# => "John Barnette"
|
112
133
|
puts user.fields
|
@@ -120,18 +141,35 @@ user.rels[:gists].href
|
|
120
141
|
**Note:** URL fields are culled into a separate `.rels` collection for easier
|
121
142
|
[Hypermedia](#hypermedia-agent) support.
|
122
143
|
|
123
|
-
|
144
|
+
## Accessing HTTP responses
|
124
145
|
|
125
146
|
While most methods return a `Resource` object or a Boolean, sometimes you may
|
126
147
|
need access to the raw HTTP response headers. You can access the last HTTP
|
127
148
|
response with `Client#last_response`:
|
128
149
|
|
129
150
|
```ruby
|
130
|
-
user =
|
131
|
-
response =
|
151
|
+
user = client.user 'andrewpthorp'
|
152
|
+
response = client.last_response
|
132
153
|
etag = response.headers[:etag]
|
133
154
|
```
|
134
155
|
|
156
|
+
## Handling errors
|
157
|
+
|
158
|
+
When the API returns an error response, Octokit will raise a Ruby exception.
|
159
|
+
|
160
|
+
A range of different exceptions can be raised depending on the error returned
|
161
|
+
by the API - for example:
|
162
|
+
|
163
|
+
* A `400 Bad Request` response will lead to an `Octokit::BadRequest` error
|
164
|
+
* A `403 Forbidden` error with a "rate limited exceeded" message will lead
|
165
|
+
to a `Octokit::TooManyRequests` error
|
166
|
+
|
167
|
+
All of the different exception classes inherit from `Octokit::Error` and
|
168
|
+
expose the `#response_status`, `#response_headers` and `#response_body`.
|
169
|
+
For validation errors, `#errors` will return an `Array` of `Hash`es
|
170
|
+
with the detailed information
|
171
|
+
[returned by the API](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#client-errors).
|
172
|
+
|
135
173
|
## Authentication
|
136
174
|
|
137
175
|
Octokit supports the various [authentication methods supported by the GitHub
|
@@ -143,14 +181,13 @@ Using your GitHub username and password is the easiest way to get started
|
|
143
181
|
making authenticated requests:
|
144
182
|
|
145
183
|
```ruby
|
146
|
-
client = Octokit::Client.new
|
147
|
-
:login => 'defunkt',
|
148
|
-
:password => 'c0d3b4ssssss!'
|
184
|
+
client = Octokit::Client.new(:login => 'defunkt', :password => 'c0d3b4ssssss!')
|
149
185
|
|
150
186
|
user = client.user
|
151
187
|
user.login
|
152
188
|
# => "defunkt"
|
153
189
|
```
|
190
|
+
|
154
191
|
While Basic Authentication allows you to get started quickly, OAuth access
|
155
192
|
tokens are the preferred way to authenticate on behalf of users.
|
156
193
|
|
@@ -159,9 +196,9 @@ tokens are the preferred way to authenticate on behalf of users.
|
|
159
196
|
[OAuth access tokens][oauth] provide two main benefits over using your username
|
160
197
|
and password:
|
161
198
|
|
162
|
-
|
199
|
+
- **Revocable access**. Access tokens can be revoked, removing access for only
|
163
200
|
that token without having to change your password everywhere.
|
164
|
-
|
201
|
+
- **Limited access**. Access tokens have [access scopes][] which allow for more
|
165
202
|
granular access to API resources. For instance, you can grant a third party
|
166
203
|
access to your gists but not your private repositories.
|
167
204
|
|
@@ -180,9 +217,7 @@ You can [create access tokens through your GitHub Account Settings](https://help
|
|
180
217
|
or with a basic authenticated Octokit client:
|
181
218
|
|
182
219
|
```ruby
|
183
|
-
client = Octokit::Client.new
|
184
|
-
:login => 'defunkt',
|
185
|
-
:password => 'c0d3b4ssssss!'
|
220
|
+
client = Octokit::Client.new(:login => 'defunkt', :password => 'c0d3b4ssssss!')
|
186
221
|
|
187
222
|
client.create_authorization(:scopes => ["user"], :note => "Name of token")
|
188
223
|
# => <your new oauth token>
|
@@ -202,7 +237,7 @@ client = Octokit::Client.new \
|
|
202
237
|
user = client.user("defunkt", :headers => { "X-GitHub-OTP" => "<your 2FA token>" })
|
203
238
|
```
|
204
239
|
|
205
|
-
As you can imagine, this gets annoying
|
240
|
+
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:
|
206
241
|
|
207
242
|
```ruby
|
208
243
|
client = Octokit::Client.new \
|
@@ -217,13 +252,14 @@ client.create_authorization(:scopes => ["user"], :note => "Name of token",
|
|
217
252
|
### Using a .netrc file
|
218
253
|
|
219
254
|
Octokit supports reading credentials from a netrc file (defaulting to
|
220
|
-
`~/.netrc`).
|
255
|
+
`~/.netrc`). Given these lines in your netrc:
|
221
256
|
|
222
257
|
```
|
223
258
|
machine api.github.com
|
224
259
|
login defunkt
|
225
260
|
password c0d3b4ssssss!
|
226
261
|
```
|
262
|
+
|
227
263
|
You can now create a client with those credentials:
|
228
264
|
|
229
265
|
```ruby
|
@@ -231,6 +267,7 @@ client = Octokit::Client.new(:netrc => true)
|
|
231
267
|
client.login
|
232
268
|
# => "defunkt"
|
233
269
|
```
|
270
|
+
|
234
271
|
But _I want to use OAuth_ you say. Since the GitHub API supports using an OAuth
|
235
272
|
token as a Basic password, you totally can:
|
236
273
|
|
@@ -263,6 +300,23 @@ user = client.user 'defunkt'
|
|
263
300
|
[access scopes]: http://developer.github.com/v3/oauth/#scopes
|
264
301
|
[app-creds]: http://developer.github.com/v3/#increasing-the-unauthenticated-rate-limit-for-oauth-applications
|
265
302
|
|
303
|
+
### GitHub App
|
304
|
+
Octokit.rb also supports authentication [using a GitHub App](https://docs.github.com/en/developers/apps/managing-github-apps/installing-github-apps), which [requires a generated JWT token](https://docs.github.com/en/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-a-github-app).
|
305
|
+
|
306
|
+
```ruby
|
307
|
+
client = Octokit::Client.new(:bearer_token => "<your jwt token>")
|
308
|
+
client.app
|
309
|
+
# => about GitHub App info
|
310
|
+
```
|
311
|
+
|
312
|
+
## Default results per_page
|
313
|
+
|
314
|
+
Default results from the GitHub API are 30, if you wish to add more you must do so during Octokit configuration.
|
315
|
+
|
316
|
+
```ruby
|
317
|
+
Octokit::Client.new(access_token: "<your 40 char token>", per_page: 100)
|
318
|
+
```
|
319
|
+
|
266
320
|
## Pagination
|
267
321
|
|
268
322
|
Many GitHub API resources are [paginated][]. While you may be tempted to start
|
@@ -271,8 +325,8 @@ previous, and last pages for you in the `Link` response header as [Hypermedia
|
|
271
325
|
link relations](#hypermedia-agent).
|
272
326
|
|
273
327
|
```ruby
|
274
|
-
issues =
|
275
|
-
issues.concat
|
328
|
+
issues = client.issues 'rails/rails'
|
329
|
+
issues.concat client.get(client.last_response.rels[:next].href)
|
276
330
|
```
|
277
331
|
|
278
332
|
### Auto pagination
|
@@ -282,13 +336,21 @@ enabled, calls for paginated resources will fetch and concatenate the results
|
|
282
336
|
from every page into a single array:
|
283
337
|
|
284
338
|
```ruby
|
285
|
-
|
286
|
-
issues =
|
339
|
+
client.auto_paginate = true
|
340
|
+
issues = client.issues 'rails/rails'
|
287
341
|
issues.length
|
288
342
|
|
289
343
|
# => 702
|
290
344
|
```
|
291
345
|
|
346
|
+
You can also enable auto pagination for all Octokit client instances:
|
347
|
+
|
348
|
+
```ruby
|
349
|
+
Octokit.configure do |c|
|
350
|
+
c.auto_paginate = true
|
351
|
+
end
|
352
|
+
```
|
353
|
+
|
292
354
|
**Note:** While Octokit auto pagination will set the page size to the maximum
|
293
355
|
`100`, and seek to not overstep your rate limit, you probably want to use a
|
294
356
|
custom pattern for traversing large lists.
|
@@ -297,16 +359,17 @@ custom pattern for traversing large lists.
|
|
297
359
|
|
298
360
|
## Working with GitHub Enterprise
|
299
361
|
|
300
|
-
With a bit of setup, you can also use Octokit with your
|
362
|
+
With a bit of setup, you can also use Octokit with your GitHub Enterprise instance.
|
301
363
|
|
302
364
|
### Interacting with the GitHub.com APIs in GitHub Enterprise
|
303
365
|
|
304
366
|
To interact with the "regular" GitHub.com APIs in GitHub Enterprise, simply configure the `api_endpoint` to match your hostname. For example:
|
305
367
|
|
306
|
-
```
|
368
|
+
```ruby
|
307
369
|
Octokit.configure do |c|
|
308
370
|
c.api_endpoint = "https://<hostname>/api/v3/"
|
309
371
|
end
|
372
|
+
|
310
373
|
client = Octokit::Client.new(:access_token => "<your 40 char token>")
|
311
374
|
```
|
312
375
|
|
@@ -314,40 +377,45 @@ client = Octokit::Client.new(:access_token => "<your 40 char token>")
|
|
314
377
|
|
315
378
|
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.
|
316
379
|
|
317
|
-
```
|
318
|
-
admin_client = Octokit::EnterpriseAdminClient.new
|
319
|
-
|
320
|
-
|
380
|
+
```ruby
|
381
|
+
admin_client = Octokit::EnterpriseAdminClient.new(
|
382
|
+
:access_token => "<your 40 char token>",
|
383
|
+
:api_endpoint => "https://<hostname>/api/v3/"
|
384
|
+
)
|
321
385
|
|
322
386
|
# or
|
323
387
|
Octokit.configure do |c|
|
324
388
|
c.api_endpoint = "https://<hostname>/api/v3/"
|
325
389
|
c.access_token = "<your 40 char token>"
|
326
390
|
end
|
327
|
-
|
391
|
+
|
392
|
+
admin_client = Octokit.enterprise_admin_client.new
|
328
393
|
```
|
329
394
|
|
330
395
|
### Interacting with the GitHub Enterprise Management Console APIs
|
331
396
|
|
332
|
-
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
|
397
|
+
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.
|
398
|
+
|
399
|
+
```ruby
|
400
|
+
management_console_client = Octokit::EnterpriseManagementConsoleClient.new(
|
401
|
+
:management_console_password => "secret",
|
402
|
+
:management_console_endpoint = "https://hostname:8633"
|
403
|
+
)
|
333
404
|
|
334
|
-
``` ruby
|
335
|
-
management_console_client = Octokit::EnterpriseManagementConsoleClient.new \
|
336
|
-
:management_console_password => "secret",
|
337
|
-
:management_console_endpoint = "https://hostname:8633"
|
338
405
|
# or
|
339
406
|
Octokit.configure do |c|
|
340
407
|
c.management_console_endpoint = "https://hostname:8633"
|
341
408
|
c.management_console_password = "secret"
|
342
409
|
end
|
343
|
-
|
410
|
+
|
411
|
+
management_console_client = Octokit.enterprise_management_console_client.new
|
344
412
|
```
|
345
413
|
|
346
414
|
### SSL Connection Errors
|
347
415
|
|
348
|
-
You
|
416
|
+
You _may_ need to disable SSL temporarily while first setting up your GitHub Enterprise install. You can do that with the following configuration:
|
349
417
|
|
350
|
-
```
|
418
|
+
```ruby
|
351
419
|
client.connection_options[:ssl] = { :verify => false }
|
352
420
|
```
|
353
421
|
|
@@ -388,7 +456,7 @@ Octokit's default.
|
|
388
456
|
|
389
457
|
```ruby
|
390
458
|
# Given $OCTOKIT_API_ENDPOINT is "http://api.github.dev"
|
391
|
-
|
459
|
+
client.api_endpoint
|
392
460
|
|
393
461
|
# => "http://api.github.dev"
|
394
462
|
```
|
@@ -397,6 +465,28 @@ Deprecation warnings and API endpoints in development preview warnings are
|
|
397
465
|
printed to STDOUT by default, these can be disabled by setting the ENV
|
398
466
|
`OCTOKIT_SILENT=true`.
|
399
467
|
|
468
|
+
### Timeouts
|
469
|
+
|
470
|
+
By default, Octokit does not timeout network requests. To set a timeout, pass in Faraday timeout settings to Octokit's `connection_options` setting.
|
471
|
+
|
472
|
+
```ruby
|
473
|
+
Octokit.configure do |c|
|
474
|
+
c.api_endpoint = ENV.fetch('GITHUB_API_ENDPOINT', 'https://api.github.com/')
|
475
|
+
c.connection_options = {
|
476
|
+
request: {
|
477
|
+
open_timeout: 5,
|
478
|
+
timeout: 5
|
479
|
+
}
|
480
|
+
}
|
481
|
+
end
|
482
|
+
```
|
483
|
+
|
484
|
+
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:
|
485
|
+
|
486
|
+
- [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/)
|
487
|
+
- [Timeout: Ruby's Most Dangerous API](https://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/)
|
488
|
+
- [The Ultimate Guide to Ruby Timeouts](https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts)
|
489
|
+
|
400
490
|
## Hypermedia agent
|
401
491
|
|
402
492
|
Starting in version 2.0, Octokit is [hypermedia][]-enabled. Under the hood,
|
@@ -408,7 +498,7 @@ Resources returned by Octokit methods contain not only data but hypermedia
|
|
408
498
|
link relations:
|
409
499
|
|
410
500
|
```ruby
|
411
|
-
user =
|
501
|
+
user = client.user 'technoweenie'
|
412
502
|
|
413
503
|
# Get the repos rel, returned from the API
|
414
504
|
# as repos_url in the resource
|
@@ -420,7 +510,7 @@ repos.last.name
|
|
420
510
|
# => "faraday-zeromq"
|
421
511
|
```
|
422
512
|
|
423
|
-
When processing API responses, all `*_url` attributes are culled
|
513
|
+
When processing API responses, all `*_url` attributes are culled into the link
|
424
514
|
relations collection. Any `url` attribute becomes `.rels[:self]`.
|
425
515
|
|
426
516
|
### URI templates
|
@@ -429,7 +519,7 @@ You might notice many link relations have variable placeholders. Octokit
|
|
429
519
|
supports [URI Templates][uri-templates] for parameterized URI expansion:
|
430
520
|
|
431
521
|
```ruby
|
432
|
-
repo =
|
522
|
+
repo = client.repo 'pengwynn/pingwynn'
|
433
523
|
rel = repo.rels[:issues]
|
434
524
|
# => #<Sawyer::Relation: issues: get https://api.github.com/repos/pengwynn/pingwynn/issues{/number}>
|
435
525
|
|
@@ -446,7 +536,7 @@ If you want to use Octokit as a pure hypermedia API client, you can start at
|
|
446
536
|
the API root and follow link relations from there:
|
447
537
|
|
448
538
|
```ruby
|
449
|
-
root =
|
539
|
+
root = client.root
|
450
540
|
root.rels[:repository].get :uri => {:owner => "octokit", :repo => "octokit.rb" }
|
451
541
|
root.rels[:user_repositories].get :uri => { :user => "octokit" },
|
452
542
|
:query => { :type => "owner" }
|
@@ -456,8 +546,8 @@ Octokit 3.0 aims to be hypermedia-driven, removing the internal URL
|
|
456
546
|
construction currently used throughout the client.
|
457
547
|
|
458
548
|
[hypermedia]: http://en.wikipedia.org/wiki/Hypermedia
|
459
|
-
[
|
460
|
-
[
|
549
|
+
[sawyer]: https://github.com/lostisland/sawyer
|
550
|
+
[faraday]: https://github.com/lostisland/faraday
|
461
551
|
[uri-templates]: http://tools.ietf.org/html/rfc6570
|
462
552
|
|
463
553
|
## Upgrading guide
|
@@ -465,8 +555,8 @@ construction currently used throughout the client.
|
|
465
555
|
Version 4.0
|
466
556
|
|
467
557
|
- **removes support for a [long-deprecated overload][list-pulls] for
|
468
|
-
passing state as a positional argument** when listing pull requests. Instead,
|
469
|
-
pass `state` in the method options.
|
558
|
+
passing state as a positional argument** when listing pull requests. Instead,
|
559
|
+
pass `state` in the method options.
|
470
560
|
- **drops support for Ruby < 2.0**.
|
471
561
|
- adds support for new [Enterprise-only APIs](#working-with-github-enterprise).
|
472
562
|
- adds support for [Repository redirects][redirects].
|
@@ -483,10 +573,11 @@ for the client:
|
|
483
573
|
```ruby
|
484
574
|
Octokit.default_media_type = "application/vnd.github.beta+json"
|
485
575
|
```
|
576
|
+
|
486
577
|
or per-request
|
487
578
|
|
488
579
|
```ruby
|
489
|
-
|
580
|
+
client.emails(:accept => "application/vnd.github.beta+json")
|
490
581
|
```
|
491
582
|
|
492
583
|
The long-deprecated `Octokit::Client#create_download` method has been removed.
|
@@ -499,21 +590,20 @@ Version 2.0 includes a completely rewritten `Client` factory that now memoizes
|
|
499
590
|
client instances based on unique configuration options. Breaking changes also
|
500
591
|
include:
|
501
592
|
|
502
|
-
|
503
|
-
|
504
|
-
|
593
|
+
- `:oauth_token` is now `:access_token`
|
594
|
+
- `:auto_traversal` is now `:auto_paginate`
|
595
|
+
- `Hashie::Mash` has been removed. Responses now return a `Sawyer::Resource`
|
505
596
|
object. This new type behaves mostly like a Ruby `Hash`, but does not fully
|
506
597
|
support the `Hashie::Mash` API.
|
507
|
-
|
598
|
+
- Two new client error types are raised where appropriate:
|
508
599
|
`Octokit::TooManyRequests` and `Octokit::TooManyLoginAttempts`
|
509
|
-
|
510
|
-
|
600
|
+
- The `search_*` methods from v1.x are now found at `legacy_search_*`
|
601
|
+
- Support for netrc requires including the [netrc gem][] in your Gemfile or
|
511
602
|
gemspec.
|
512
|
-
|
603
|
+
- DateTime fields are now proper `DateTime` objects. Previous versions outputted DateTime fields as 'String' objects.
|
513
604
|
|
514
605
|
[netrc gem]: https://rubygems.org/gems/netrc
|
515
606
|
|
516
|
-
|
517
607
|
## Advanced usage
|
518
608
|
|
519
609
|
Since Octokit employs [Faraday][faraday] under the hood, some behavior can be
|
@@ -527,13 +617,21 @@ traffic:
|
|
527
617
|
|
528
618
|
```ruby
|
529
619
|
stack = Faraday::RackBuilder.new do |builder|
|
530
|
-
builder.
|
620
|
+
builder.use Faraday::Retry::Middleware, exceptions: Faraday::Request::Retry::DEFAULT_EXCEPTIONS + [Octokit::ServerError] # or Faraday::Request::Retry for Faraday < 2.0
|
621
|
+
builder.use Octokit::Middleware::FollowRedirects
|
531
622
|
builder.use Octokit::Response::RaiseError
|
623
|
+
builder.use Octokit::Response::FeedParser
|
624
|
+
builder.response :logger do |logger|
|
625
|
+
logger.filter(/(Authorization: "(token|Bearer) )(\w+)/, '\1[REMOVED]')
|
626
|
+
end
|
532
627
|
builder.adapter Faraday.default_adapter
|
533
628
|
end
|
534
629
|
Octokit.middleware = stack
|
535
|
-
|
630
|
+
|
631
|
+
client = Octokit::Client.new
|
632
|
+
client.user 'pengwynn'
|
536
633
|
```
|
634
|
+
|
537
635
|
```
|
538
636
|
I, [2013-08-22T15:54:38.583300 #88227] INFO -- : get https://api.github.com/users/pengwynn
|
539
637
|
D, [2013-08-22T15:54:38.583401 #88227] DEBUG -- request: Accept: "application/vnd.github.beta+json"
|
@@ -577,8 +675,7 @@ Once configured, the middleware will store responses in cache based on ETag
|
|
577
675
|
fingerprint and serve those back up for future `304` responses for the same
|
578
676
|
resource. See the [project README][cache] for advanced usage.
|
579
677
|
|
580
|
-
|
581
|
-
[cache]: https://github.com/plataformatec/faraday-http-cache
|
678
|
+
[cache]: https://github.com/sourcelevel/faraday-http-cache
|
582
679
|
[faraday]: https://github.com/lostisland/faraday
|
583
680
|
|
584
681
|
## Hacking on Octokit.rb
|
@@ -593,8 +690,13 @@ to run a Ruby console to poke on Octokit, you can crank one up with:
|
|
593
690
|
|
594
691
|
script/console
|
595
692
|
|
596
|
-
Using the scripts in `./
|
597
|
-
|
693
|
+
Using the scripts in `./script` instead of `bundle exec rspec`, `bundle console`, etc. ensures your dependencies are up-to-date.
|
694
|
+
|
695
|
+
### Code of Conduct
|
696
|
+
|
697
|
+
We want both the Octokit.rb and larger Octokit communities to be open
|
698
|
+
and welcoming environments. Please read and follow both in spirit and
|
699
|
+
letter [Code of Conduct](CODE_OF_CONDUCT.md).
|
598
700
|
|
599
701
|
### Running and writing new tests
|
600
702
|
|
@@ -609,50 +711,53 @@ Octokit uses environmental variables for storing credentials used in testing.
|
|
609
711
|
If you are testing an API endpoint that doesn't require authentication, you
|
610
712
|
can get away without any additional configuration. For the most part, tests
|
611
713
|
use an authenticated client, using a token stored in `ENV['OCTOKIT_TEST_GITHUB_TOKEN']`.
|
612
|
-
There are several different
|
714
|
+
There are several different authentication methods used across the api.
|
613
715
|
Here is the full list of configurable environmental variables for testing
|
614
716
|
Octokit:
|
615
717
|
|
616
|
-
ENV Variable
|
617
|
-
|
618
|
-
`OCTOKIT_TEST_GITHUB_LOGIN
|
619
|
-
`OCTOKIT_TEST_GITHUB_PASSWORD
|
620
|
-
`OCTOKIT_TEST_GITHUB_TOKEN`
|
621
|
-
`OCTOKIT_TEST_GITHUB_CLIENT_ID`
|
622
|
-
`OCTOKIT_TEST_GITHUB_CLIENT_SECRET`
|
623
|
-
`OCTOKIT_TEST_GITHUB_REPOSITORY`
|
624
|
-
`OCTOKIT_TEST_GITHUB_ORGANIZATION`
|
625
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN`
|
626
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN`
|
627
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password
|
628
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT`
|
629
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint
|
718
|
+
| ENV Variable | Description |
|
719
|
+
| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
720
|
+
| `OCTOKIT_TEST_GITHUB_LOGIN` | GitHub login name (preferably one created specifically for testing against). |
|
721
|
+
| `OCTOKIT_TEST_GITHUB_PASSWORD` | Password for the test GitHub login. |
|
722
|
+
| `OCTOKIT_TEST_GITHUB_TOKEN` | [Personal Access Token](https://github.com/blog/1509-personal-api-tokens) for the test GitHub login. |
|
723
|
+
| `OCTOKIT_TEST_GITHUB_CLIENT_ID` | Test OAuth application client id. |
|
724
|
+
| `OCTOKIT_TEST_GITHUB_CLIENT_SECRET` | Test OAuth application client secret. |
|
725
|
+
| `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` |
|
726
|
+
| `OCTOKIT_TEST_GITHUB_ORGANIZATION` | Test organization. |
|
727
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN` | GitHub Enterprise login name. |
|
728
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN` | GitHub Enterprise token. |
|
729
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password. |
|
730
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT` | GitHub Enterprise hostname. |
|
731
|
+
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint. |
|
732
|
+
| `OCTOKIT_TEST_GITHUB_INTEGRATION` | [GitHub Integration](https://developer.github.com/early-access/integrations/) owned by your test organization. |
|
733
|
+
| `OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION` | Installation of the GitHub Integration specified above. |
|
734
|
+
| `OCTOKIT_TEST_INTEGRATION_PEM_KEY` | File path to the private key generated from your integration. |
|
630
735
|
|
631
736
|
Since we periodically refresh our cassettes, please keep some points in mind
|
632
737
|
when writing new specs.
|
633
738
|
|
634
|
-
|
739
|
+
- **Specs should be idempotent**. The HTTP calls made during a spec should be
|
635
740
|
able to be run over and over. This means deleting a known resource prior to
|
636
741
|
creating it if the name has to be unique.
|
637
|
-
|
742
|
+
- **Specs should be able to be run in random order.** If a spec depends on
|
638
743
|
another resource as a fixture, make sure that's created in the scope of the
|
639
744
|
spec and not depend on a previous spec to create the data needed.
|
640
|
-
|
745
|
+
- **Do not depend on authenticated user info.** Instead of asserting
|
641
746
|
actual values in resources, try to assert the existence of a key or that a
|
642
747
|
response is an Array. We're testing the client, not the API.
|
643
748
|
|
644
749
|
[bootstrapping]: http://wynnnetherland.com/linked/2013012801/bootstrapping-consistency
|
645
|
-
[
|
750
|
+
[vcr]: https://github.com/vcr/vcr
|
646
751
|
|
647
752
|
## Supported Ruby Versions
|
648
753
|
|
649
|
-
This library aims to support and is [tested against][
|
754
|
+
This library aims to support and is [tested against][actions] the following Ruby
|
650
755
|
implementations:
|
651
756
|
|
652
|
-
* Ruby 2.
|
653
|
-
* Ruby
|
654
|
-
* Ruby
|
655
|
-
* Ruby 2
|
757
|
+
* Ruby 2.7
|
758
|
+
* Ruby 3.0
|
759
|
+
* Ruby 3.1
|
760
|
+
* Ruby 3.2
|
656
761
|
|
657
762
|
If something doesn't work on one of these Ruby versions, it's a bug.
|
658
763
|
|
@@ -667,7 +772,7 @@ implementation, you will be responsible for providing patches in a timely
|
|
667
772
|
fashion. If critical issues for a particular implementation exist at the time
|
668
773
|
of a major release, support for that Ruby version may be dropped.
|
669
774
|
|
670
|
-
[
|
775
|
+
[actions]: https://github.com/octokit/octokit.rb/actions
|
671
776
|
|
672
777
|
## Versioning
|
673
778
|
|
@@ -688,6 +793,22 @@ The changes made between versions can be seen on the [project releases page][rel
|
|
688
793
|
[pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
|
689
794
|
[releases]: https://github.com/octokit/octokit.rb/releases
|
690
795
|
|
796
|
+
## Making Repeating Requests
|
797
|
+
|
798
|
+
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.
|
799
|
+
|
800
|
+
```ruby
|
801
|
+
Octopoller.poll(timeout: 15.seconds) do
|
802
|
+
begin
|
803
|
+
client.request_progress # ex. request a long running job's status
|
804
|
+
rescue Error
|
805
|
+
:re_poll
|
806
|
+
end
|
807
|
+
end
|
808
|
+
```
|
809
|
+
|
810
|
+
This is useful when making requests for a long running job's progress (ex. requesting a [Source Import's progress](https://developer.github.com/v3/migrations/source_imports/#get-import-progress)).
|
811
|
+
|
691
812
|
## License
|
692
813
|
|
693
814
|
Copyright (c) 2009-2014 Wynn Netherland, Adam Stacoviak, Erik Michaels-Ober
|