octokit 4.22.0 → 7.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +113 -75
- data/Rakefile +20 -14
- data/lib/ext/sawyer/relation.rb +4 -2
- data/lib/octokit/arguments.rb +2 -2
- data/lib/octokit/authentication.rb +10 -3
- data/lib/octokit/client/actions_artifacts.rb +71 -0
- data/lib/octokit/client/actions_secrets.rb +10 -9
- data/lib/octokit/client/actions_workflow_jobs.rb +65 -0
- data/lib/octokit/client/actions_workflow_runs.rb +23 -3
- data/lib/octokit/client/actions_workflows.rb +27 -2
- data/lib/octokit/client/apps.rb +26 -26
- data/lib/octokit/client/checks.rb +18 -9
- data/lib/octokit/client/code_scanning.rb +53 -0
- data/lib/octokit/client/codespaces_secrets.rb +59 -0
- data/lib/octokit/client/commit_branches.rb +2 -2
- data/lib/octokit/client/commit_comments.rb +8 -8
- data/lib/octokit/client/commit_pulls.rb +2 -2
- data/lib/octokit/client/commits.rb +25 -33
- data/lib/octokit/client/community_profile.rb +2 -3
- data/lib/octokit/client/contents.rb +20 -21
- data/lib/octokit/client/dependabot_secrets.rb +59 -0
- data/lib/octokit/client/deployments.rb +6 -6
- 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 -5
- 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 +0 -6
- data/lib/octokit/client/objects.rb +14 -14
- data/lib/octokit/client/organizations.rb +100 -56
- data/lib/octokit/client/pages.rb +5 -7
- data/lib/octokit/client/projects.rb +44 -64
- data/lib/octokit/client/pub_sub_hubbub.rb +15 -15
- data/lib/octokit/client/pull_requests.rb +54 -42
- data/lib/octokit/client/rate_limit.rb +9 -11
- data/lib/octokit/client/reactions.rb +13 -16
- data/lib/octokit/client/refs.rb +14 -17
- data/lib/octokit/client/releases.rb +13 -13
- data/lib/octokit/client/repositories.rb +49 -69
- data/lib/octokit/client/repository_invitations.rb +3 -3
- data/lib/octokit/client/reviews.rb +8 -8
- data/lib/octokit/client/say.rb +4 -5
- data/lib/octokit/client/search.rb +24 -10
- 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 +27 -33
- data/lib/octokit/client.rb +40 -16
- data/lib/octokit/configurable.rb +34 -30
- data/lib/octokit/connection.rb +28 -21
- data/lib/octokit/default.rb +48 -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 +45 -34
- data/lib/octokit/gist.rb +3 -4
- data/lib/octokit/middleware/follow_redirects.rb +12 -11
- data/lib/octokit/organization.rb +3 -1
- data/lib/octokit/rate_limit.rb +8 -6
- 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 -7
- data/lib/octokit/response/raise_error.rb +4 -4
- 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 -11
- metadata +20 -33
- data/lib/octokit/client/authorizations.rb +0 -182
- 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: 398b3f7b1ccfb89b207c3bb654fe34617a4fade1e86b1d9bd7909180b702bc38
|
4
|
+
data.tar.gz: c00f669f44e74b19861c4bd86042aa67e05f272a64021c406aa8a4d6884ad0fd
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 7d9034260fe94ee7fd55e117457592c36d34777d49ab3efe2ad526c6551e3a2a18a4f4ac1c17df88af53436115f3d6435128bbde1701f48c6647acfb9a396fbd
|
7
|
+
data.tar.gz: 0151f0ec5966df0bb940fe979cf73c1c646aed1f1ff75b050a3e39890c706aa078ef64ae7e5c6efa56f010c78f050913390346d8a2511946bbe731c7dcadb1bb
|
data/README.md
CHANGED
@@ -1,5 +1,8 @@
|
|
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
8
|
![logo](https://docs.github.com/assets/images/gundamcat.png)
|
@@ -10,43 +13,47 @@ 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](#installation)
|
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
|
+
6. [GitHub App](#github-app)
|
29
|
+
8. [Default results per_page](#default-results-per_page)
|
30
|
+
9. [Pagination](#pagination)
|
24
31
|
1. [Auto pagination](#auto-pagination)
|
25
|
-
|
32
|
+
10. [Working with GitHub Enterprise](#working-with-github-enterprise)
|
26
33
|
1. [Interacting with the GitHub.com APIs in GitHub Enterprise](#interacting-with-the-githubcom-apis-in-github-enterprise)
|
27
34
|
2. [Interacting with the GitHub Enterprise Admin APIs](#interacting-with-the-github-enterprise-admin-apis)
|
28
35
|
3. [Interacting with the GitHub Enterprise Management Console APIs](#interacting-with-the-github-enterprise-management-console-apis)
|
29
|
-
|
30
|
-
|
36
|
+
4. [SSL Connection Errors](#ssl-connection-errors)
|
37
|
+
11. [Configuration and defaults](#configuration-and-defaults)
|
31
38
|
1. [Configuring module defaults](#configuring-module-defaults)
|
32
39
|
2. [Using ENV variables](#using-env-variables)
|
33
40
|
3. [Timeouts](#timeouts)
|
34
|
-
|
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
|
-
|
50
|
+
15. [Hacking on Octokit.rb](#hacking-on-octokitrb)
|
44
51
|
1. [Code of Conduct](#code-of-conduct)
|
45
52
|
2. [Running and writing new tests](#running-and-writing-new-tests)
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
53
|
+
16. [Supported Ruby Versions](#supported-ruby-versions)
|
54
|
+
17. [Versioning](#versioning)
|
55
|
+
18. [Making Repeating Requests](#making-repeating-requests)
|
56
|
+
19. [License](#license)
|
50
57
|
|
51
58
|
## Philosophy
|
52
59
|
|
@@ -66,7 +73,7 @@ client.readme 'al3x/sovereign', :accept => 'application/vnd.github.html'
|
|
66
73
|
[wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper
|
67
74
|
[github-api]: https://developer.github.com/v3/
|
68
75
|
|
69
|
-
##
|
76
|
+
## Installation
|
70
77
|
|
71
78
|
Install via Rubygems
|
72
79
|
|
@@ -74,13 +81,13 @@ Install via Rubygems
|
|
74
81
|
|
75
82
|
... or add to your Gemfile
|
76
83
|
|
77
|
-
gem "octokit", "~>
|
84
|
+
gem "octokit", "~> 5.0"
|
78
85
|
|
79
86
|
Access the library in Ruby:
|
80
87
|
|
81
88
|
require 'octokit'
|
82
89
|
|
83
|
-
|
90
|
+
## Making requests
|
84
91
|
|
85
92
|
[API methods][] are available as client instance methods.
|
86
93
|
|
@@ -95,7 +102,7 @@ client = Octokit::Client.new(:access_token => 'personal_access_token')
|
|
95
102
|
client.user
|
96
103
|
```
|
97
104
|
|
98
|
-
### Additional
|
105
|
+
### Additional query parameters
|
99
106
|
|
100
107
|
When passing additional parameters to GET based request use the following syntax:
|
101
108
|
|
@@ -109,9 +116,9 @@ When passing additional parameters to GET based request use the following syntax
|
|
109
116
|
client.contents('octokit/octokit.rb', path: 'path/to/file.rb', query: {ref: 'some-other-branch'})
|
110
117
|
```
|
111
118
|
|
112
|
-
[
|
119
|
+
[api methods]: http://octokit.github.io/octokit.rb/method_list.html
|
113
120
|
|
114
|
-
|
121
|
+
## Consuming resources
|
115
122
|
|
116
123
|
Most methods return a `Resource` object which provides dot notation and `[]`
|
117
124
|
access for fields returned in the API response.
|
@@ -134,7 +141,7 @@ user.rels[:gists].href
|
|
134
141
|
**Note:** URL fields are culled into a separate `.rels` collection for easier
|
135
142
|
[Hypermedia](#hypermedia-agent) support.
|
136
143
|
|
137
|
-
|
144
|
+
## Accessing HTTP responses
|
138
145
|
|
139
146
|
While most methods return a `Resource` object or a Boolean, sometimes you may
|
140
147
|
need access to the raw HTTP response headers. You can access the last HTTP
|
@@ -146,6 +153,23 @@ response = client.last_response
|
|
146
153
|
etag = response.headers[:etag]
|
147
154
|
```
|
148
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
|
+
|
149
173
|
## Authentication
|
150
174
|
|
151
175
|
Octokit supports the various [authentication methods supported by the GitHub
|
@@ -163,6 +187,7 @@ user = client.user
|
|
163
187
|
user.login
|
164
188
|
# => "defunkt"
|
165
189
|
```
|
190
|
+
|
166
191
|
While Basic Authentication allows you to get started quickly, OAuth access
|
167
192
|
tokens are the preferred way to authenticate on behalf of users.
|
168
193
|
|
@@ -171,9 +196,9 @@ tokens are the preferred way to authenticate on behalf of users.
|
|
171
196
|
[OAuth access tokens][oauth] provide two main benefits over using your username
|
172
197
|
and password:
|
173
198
|
|
174
|
-
|
199
|
+
- **Revocable access**. Access tokens can be revoked, removing access for only
|
175
200
|
that token without having to change your password everywhere.
|
176
|
-
|
201
|
+
- **Limited access**. Access tokens have [access scopes][] which allow for more
|
177
202
|
granular access to API resources. For instance, you can grant a third party
|
178
203
|
access to your gists but not your private repositories.
|
179
204
|
|
@@ -212,7 +237,7 @@ client = Octokit::Client.new \
|
|
212
237
|
user = client.user("defunkt", :headers => { "X-GitHub-OTP" => "<your 2FA token>" })
|
213
238
|
```
|
214
239
|
|
215
|
-
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:
|
216
241
|
|
217
242
|
```ruby
|
218
243
|
client = Octokit::Client.new \
|
@@ -227,13 +252,14 @@ client.create_authorization(:scopes => ["user"], :note => "Name of token",
|
|
227
252
|
### Using a .netrc file
|
228
253
|
|
229
254
|
Octokit supports reading credentials from a netrc file (defaulting to
|
230
|
-
`~/.netrc`).
|
255
|
+
`~/.netrc`). Given these lines in your netrc:
|
231
256
|
|
232
257
|
```
|
233
258
|
machine api.github.com
|
234
259
|
login defunkt
|
235
260
|
password c0d3b4ssssss!
|
236
261
|
```
|
262
|
+
|
237
263
|
You can now create a client with those credentials:
|
238
264
|
|
239
265
|
```ruby
|
@@ -241,6 +267,7 @@ client = Octokit::Client.new(:netrc => true)
|
|
241
267
|
client.login
|
242
268
|
# => "defunkt"
|
243
269
|
```
|
270
|
+
|
244
271
|
But _I want to use OAuth_ you say. Since the GitHub API supports using an OAuth
|
245
272
|
token as a Basic password, you totally can:
|
246
273
|
|
@@ -273,6 +300,15 @@ user = client.user 'defunkt'
|
|
273
300
|
[access scopes]: http://developer.github.com/v3/oauth/#scopes
|
274
301
|
[app-creds]: http://developer.github.com/v3/#increasing-the-unauthenticated-rate-limit-for-oauth-applications
|
275
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
|
+
|
276
312
|
## Default results per_page
|
277
313
|
|
278
314
|
Default results from the GitHub API are 30, if you wish to add more you must do so during Octokit configuration.
|
@@ -329,7 +365,7 @@ With a bit of setup, you can also use Octokit with your GitHub Enterprise instan
|
|
329
365
|
|
330
366
|
To interact with the "regular" GitHub.com APIs in GitHub Enterprise, simply configure the `api_endpoint` to match your hostname. For example:
|
331
367
|
|
332
|
-
```
|
368
|
+
```ruby
|
333
369
|
Octokit.configure do |c|
|
334
370
|
c.api_endpoint = "https://<hostname>/api/v3/"
|
335
371
|
end
|
@@ -341,7 +377,7 @@ client = Octokit::Client.new(:access_token => "<your 40 char token>")
|
|
341
377
|
|
342
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.
|
343
379
|
|
344
|
-
```
|
380
|
+
```ruby
|
345
381
|
admin_client = Octokit::EnterpriseAdminClient.new(
|
346
382
|
:access_token => "<your 40 char token>",
|
347
383
|
:api_endpoint => "https://<hostname>/api/v3/"
|
@@ -358,9 +394,9 @@ admin_client = Octokit.enterprise_admin_client.new
|
|
358
394
|
|
359
395
|
### Interacting with the GitHub Enterprise Management Console APIs
|
360
396
|
|
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
|
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.
|
362
398
|
|
363
|
-
```
|
399
|
+
```ruby
|
364
400
|
management_console_client = Octokit::EnterpriseManagementConsoleClient.new(
|
365
401
|
:management_console_password => "secret",
|
366
402
|
:management_console_endpoint = "https://hostname:8633"
|
@@ -377,9 +413,9 @@ management_console_client = Octokit.enterprise_management_console_client.new
|
|
377
413
|
|
378
414
|
### SSL Connection Errors
|
379
415
|
|
380
|
-
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:
|
381
417
|
|
382
|
-
```
|
418
|
+
```ruby
|
383
419
|
client.connection_options[:ssl] = { :verify => false }
|
384
420
|
```
|
385
421
|
|
@@ -444,6 +480,7 @@ Octokit.configure do |c|
|
|
444
480
|
}
|
445
481
|
end
|
446
482
|
```
|
483
|
+
|
447
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:
|
448
485
|
|
449
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/)
|
@@ -473,7 +510,7 @@ repos.last.name
|
|
473
510
|
# => "faraday-zeromq"
|
474
511
|
```
|
475
512
|
|
476
|
-
When processing API responses, all `*_url` attributes are culled
|
513
|
+
When processing API responses, all `*_url` attributes are culled into the link
|
477
514
|
relations collection. Any `url` attribute becomes `.rels[:self]`.
|
478
515
|
|
479
516
|
### URI templates
|
@@ -509,8 +546,8 @@ Octokit 3.0 aims to be hypermedia-driven, removing the internal URL
|
|
509
546
|
construction currently used throughout the client.
|
510
547
|
|
511
548
|
[hypermedia]: http://en.wikipedia.org/wiki/Hypermedia
|
512
|
-
[
|
513
|
-
[
|
549
|
+
[sawyer]: https://github.com/lostisland/sawyer
|
550
|
+
[faraday]: https://github.com/lostisland/faraday
|
514
551
|
[uri-templates]: http://tools.ietf.org/html/rfc6570
|
515
552
|
|
516
553
|
## Upgrading guide
|
@@ -518,8 +555,8 @@ construction currently used throughout the client.
|
|
518
555
|
Version 4.0
|
519
556
|
|
520
557
|
- **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.
|
558
|
+
passing state as a positional argument** when listing pull requests. Instead,
|
559
|
+
pass `state` in the method options.
|
523
560
|
- **drops support for Ruby < 2.0**.
|
524
561
|
- adds support for new [Enterprise-only APIs](#working-with-github-enterprise).
|
525
562
|
- adds support for [Repository redirects][redirects].
|
@@ -536,6 +573,7 @@ for the client:
|
|
536
573
|
```ruby
|
537
574
|
Octokit.default_media_type = "application/vnd.github.beta+json"
|
538
575
|
```
|
576
|
+
|
539
577
|
or per-request
|
540
578
|
|
541
579
|
```ruby
|
@@ -552,21 +590,20 @@ Version 2.0 includes a completely rewritten `Client` factory that now memoizes
|
|
552
590
|
client instances based on unique configuration options. Breaking changes also
|
553
591
|
include:
|
554
592
|
|
555
|
-
|
556
|
-
|
557
|
-
|
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`
|
558
596
|
object. This new type behaves mostly like a Ruby `Hash`, but does not fully
|
559
597
|
support the `Hashie::Mash` API.
|
560
|
-
|
598
|
+
- Two new client error types are raised where appropriate:
|
561
599
|
`Octokit::TooManyRequests` and `Octokit::TooManyLoginAttempts`
|
562
|
-
|
563
|
-
|
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
|
564
602
|
gemspec.
|
565
|
-
|
603
|
+
- DateTime fields are now proper `DateTime` objects. Previous versions outputted DateTime fields as 'String' objects.
|
566
604
|
|
567
605
|
[netrc gem]: https://rubygems.org/gems/netrc
|
568
606
|
|
569
|
-
|
570
607
|
## Advanced usage
|
571
608
|
|
572
609
|
Since Octokit employs [Faraday][faraday] under the hood, some behavior can be
|
@@ -580,7 +617,7 @@ traffic:
|
|
580
617
|
|
581
618
|
```ruby
|
582
619
|
stack = Faraday::RackBuilder.new do |builder|
|
583
|
-
builder.use Faraday::
|
620
|
+
builder.use Faraday::Retry::Middleware, exceptions: Faraday::Request::Retry::DEFAULT_EXCEPTIONS + [Octokit::ServerError] # or Faraday::Request::Retry for Faraday < 2.0
|
584
621
|
builder.use Octokit::Middleware::FollowRedirects
|
585
622
|
builder.use Octokit::Response::RaiseError
|
586
623
|
builder.use Octokit::Response::FeedParser
|
@@ -594,6 +631,7 @@ Octokit.middleware = stack
|
|
594
631
|
client = Octokit::Client.new
|
595
632
|
client.user 'pengwynn'
|
596
633
|
```
|
634
|
+
|
597
635
|
```
|
598
636
|
I, [2013-08-22T15:54:38.583300 #88227] INFO -- : get https://api.github.com/users/pengwynn
|
599
637
|
D, [2013-08-22T15:54:38.583401 #88227] DEBUG -- request: Accept: "application/vnd.github.beta+json"
|
@@ -637,8 +675,7 @@ Once configured, the middleware will store responses in cache based on ETag
|
|
637
675
|
fingerprint and serve those back up for future `304` responses for the same
|
638
676
|
resource. See the [project README][cache] for advanced usage.
|
639
677
|
|
640
|
-
|
641
|
-
[cache]: https://github.com/plataformatec/faraday-http-cache
|
678
|
+
[cache]: https://github.com/sourcelevel/faraday-http-cache
|
642
679
|
[faraday]: https://github.com/lostisland/faraday
|
643
680
|
|
644
681
|
## Hacking on Octokit.rb
|
@@ -653,12 +690,11 @@ to run a Ruby console to poke on Octokit, you can crank one up with:
|
|
653
690
|
|
654
691
|
script/console
|
655
692
|
|
656
|
-
Using the scripts in `./script` instead of `bundle exec rspec`, `bundle
|
657
|
-
console`, etc. ensures your dependencies are up-to-date.
|
693
|
+
Using the scripts in `./script` instead of `bundle exec rspec`, `bundle console`, etc. ensures your dependencies are up-to-date.
|
658
694
|
|
659
695
|
### Code of Conduct
|
660
696
|
|
661
|
-
We want both the Octokit.rb and larger Octokit communities to be
|
697
|
+
We want both the Octokit.rb and larger Octokit communities to be open
|
662
698
|
and welcoming environments. Please read and follow both in spirit and
|
663
699
|
letter [Code of Conduct](CODE_OF_CONDUCT.md).
|
664
700
|
|
@@ -675,52 +711,53 @@ Octokit uses environmental variables for storing credentials used in testing.
|
|
675
711
|
If you are testing an API endpoint that doesn't require authentication, you
|
676
712
|
can get away without any additional configuration. For the most part, tests
|
677
713
|
use an authenticated client, using a token stored in `ENV['OCTOKIT_TEST_GITHUB_TOKEN']`.
|
678
|
-
There are several different
|
714
|
+
There are several different authentication methods used across the api.
|
679
715
|
Here is the full list of configurable environmental variables for testing
|
680
716
|
Octokit:
|
681
717
|
|
682
|
-
ENV Variable
|
683
|
-
|
684
|
-
`OCTOKIT_TEST_GITHUB_LOGIN
|
685
|
-
`OCTOKIT_TEST_GITHUB_PASSWORD
|
686
|
-
`OCTOKIT_TEST_GITHUB_TOKEN`
|
687
|
-
`OCTOKIT_TEST_GITHUB_CLIENT_ID`
|
688
|
-
`OCTOKIT_TEST_GITHUB_CLIENT_SECRET`
|
689
|
-
`OCTOKIT_TEST_GITHUB_REPOSITORY`
|
690
|
-
`OCTOKIT_TEST_GITHUB_ORGANIZATION`
|
691
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN`
|
692
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN`
|
693
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password.
|
694
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT`
|
695
|
-
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint.
|
696
|
-
`OCTOKIT_TEST_GITHUB_INTEGRATION`
|
697
|
-
`OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION`
|
698
|
-
`OCTOKIT_TEST_INTEGRATION_PEM_KEY`
|
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. |
|
699
735
|
|
700
736
|
Since we periodically refresh our cassettes, please keep some points in mind
|
701
737
|
when writing new specs.
|
702
738
|
|
703
|
-
|
739
|
+
- **Specs should be idempotent**. The HTTP calls made during a spec should be
|
704
740
|
able to be run over and over. This means deleting a known resource prior to
|
705
741
|
creating it if the name has to be unique.
|
706
|
-
|
742
|
+
- **Specs should be able to be run in random order.** If a spec depends on
|
707
743
|
another resource as a fixture, make sure that's created in the scope of the
|
708
744
|
spec and not depend on a previous spec to create the data needed.
|
709
|
-
|
745
|
+
- **Do not depend on authenticated user info.** Instead of asserting
|
710
746
|
actual values in resources, try to assert the existence of a key or that a
|
711
747
|
response is an Array. We're testing the client, not the API.
|
712
748
|
|
713
749
|
[bootstrapping]: http://wynnnetherland.com/linked/2013012801/bootstrapping-consistency
|
714
|
-
[
|
750
|
+
[vcr]: https://github.com/vcr/vcr
|
715
751
|
|
716
752
|
## Supported Ruby Versions
|
717
753
|
|
718
754
|
This library aims to support and is [tested against][actions] the following Ruby
|
719
755
|
implementations:
|
720
756
|
|
721
|
-
* Ruby 2.5
|
722
|
-
* Ruby 2.6
|
723
757
|
* Ruby 2.7
|
758
|
+
* Ruby 3.0
|
759
|
+
* Ruby 3.1
|
760
|
+
* Ruby 3.2
|
724
761
|
|
725
762
|
If something doesn't work on one of these Ruby versions, it's a bug.
|
726
763
|
|
@@ -757,7 +794,8 @@ The changes made between versions can be seen on the [project releases page][rel
|
|
757
794
|
[releases]: https://github.com/octokit/octokit.rb/releases
|
758
795
|
|
759
796
|
## Making Repeating Requests
|
760
|
-
|
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.
|
761
799
|
|
762
800
|
```ruby
|
763
801
|
Octopoller.poll(timeout: 15.seconds) do
|
data/Rakefile
CHANGED
@@ -1,22 +1,28 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
1
3
|
require 'bundler'
|
2
4
|
Bundler::GemHelper.install_tasks
|
3
5
|
|
4
|
-
|
5
|
-
|
6
|
+
task test: :spec
|
7
|
+
task default: :spec
|
6
8
|
|
7
|
-
|
8
|
-
task :
|
9
|
+
desc 'Run RSpec'
|
10
|
+
task :spec do
|
11
|
+
if Process.respond_to?(:fork)
|
12
|
+
sh('rspec-queue')
|
13
|
+
else
|
14
|
+
sh('rspec')
|
15
|
+
end
|
16
|
+
end
|
9
17
|
|
10
18
|
namespace :doc do
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
]
|
19
|
-
end
|
20
|
-
rescue LoadError
|
19
|
+
require 'yard'
|
20
|
+
YARD::Rake::YardocTask.new do |task|
|
21
|
+
task.files = ['README.md', 'LICENSE.md', 'lib/**/*.rb']
|
22
|
+
task.options = [
|
23
|
+
'--output-dir', 'doc/yard',
|
24
|
+
'--markup', 'markdown'
|
25
|
+
]
|
21
26
|
end
|
27
|
+
rescue LoadError
|
22
28
|
end
|
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
|
@@ -66,8 +74,7 @@ module Octokit
|
|
66
74
|
self.password = creds.shift
|
67
75
|
end
|
68
76
|
rescue LoadError
|
69
|
-
octokit_warn
|
77
|
+
octokit_warn 'Please install netrc gem for .netrc support'
|
70
78
|
end
|
71
|
-
|
72
79
|
end
|
73
80
|
end
|
@@ -0,0 +1,71 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
module Octokit
|
4
|
+
class Client
|
5
|
+
# Methods for the Actions Artifacts API
|
6
|
+
#
|
7
|
+
# @see https://developer.github.com/v3/actions/artifacts
|
8
|
+
module ActionsArtifacts
|
9
|
+
# List all artifacts for a repository
|
10
|
+
#
|
11
|
+
# @param repo [Integer, String, Repository, Hash] A GitHub repository
|
12
|
+
#
|
13
|
+
# @return [Sawyer::Resource] the total count and an array of artifacts
|
14
|
+
# @see https://developer.github.com/v3/actions/artifacts#list-artifacts-for-a-repository
|
15
|
+
def repository_artifacts(repo, options = {})
|
16
|
+
paginate "#{Repository.path repo}/actions/artifacts", options do |data, last_response|
|
17
|
+
data.artifacts.concat last_response.data.artifacts
|
18
|
+
end
|
19
|
+
end
|
20
|
+
|
21
|
+
# List all artifacts for a workflow run
|
22
|
+
#
|
23
|
+
# @param repo [Integer, String, Repository, Hash] A GitHub repository
|
24
|
+
# @param workflow_run_id [Integer] Id of a workflow run
|
25
|
+
#
|
26
|
+
# @return [Sawyer::Resource] the total count and an array of artifacts
|
27
|
+
# @see https://docs.github.com/en/rest/actions/artifacts#list-workflow-run-artifacts
|
28
|
+
def workflow_run_artifacts(repo, workflow_run_id, options = {})
|
29
|
+
paginate "#{Repository.path repo}/actions/runs/#{workflow_run_id}/artifacts", options do |data, last_response|
|
30
|
+
data.artifacts.concat last_response.data.artifacts
|
31
|
+
end
|
32
|
+
end
|
33
|
+
|
34
|
+
# Get an artifact
|
35
|
+
#
|
36
|
+
# @param repo [Integer, String, Repository, Hash] A GitHub repository
|
37
|
+
# @param id [Integer] Id of an artifact
|
38
|
+
#
|
39
|
+
# @return [Sawyer::Resource] Artifact information
|
40
|
+
# @see https://docs.github.com/en/rest/actions/artifacts#get-an-artifact
|
41
|
+
def artifact(repo, id, options = {})
|
42
|
+
get "#{Repository.path repo}/actions/artifacts/#{id}", options
|
43
|
+
end
|
44
|
+
|
45
|
+
# Get a download URL for an artifact
|
46
|
+
#
|
47
|
+
# @param repo [Integer, String, Repository, Hash] A GitHub repository
|
48
|
+
# @param id [Integer] Id of an artifact
|
49
|
+
#
|
50
|
+
# @return [String] URL to the .zip archive of the artifact
|
51
|
+
# @see https://docs.github.com/en/rest/actions/artifacts#download-an-artifact
|
52
|
+
def artifact_download_url(repo, id, options = {})
|
53
|
+
url = "#{Repository.path repo}/actions/artifacts/#{id}/zip"
|
54
|
+
|
55
|
+
response = client_without_redirects.head(url, options)
|
56
|
+
response.headers['Location']
|
57
|
+
end
|
58
|
+
|
59
|
+
# Delete an artifact
|
60
|
+
#
|
61
|
+
# @param repo [Integer, String, Repository, Hash] A GitHub repository
|
62
|
+
# @param id [Integer] Id of an artifact
|
63
|
+
#
|
64
|
+
# @return [Boolean] Return true if the artifact was successfully deleted
|
65
|
+
# @see https://docs.github.com/en/rest/actions/artifacts#delete-an-artifact
|
66
|
+
def delete_artifact(repo, id, options = {})
|
67
|
+
boolean_from_response :delete, "#{Repository.path repo}/actions/artifacts/#{id}", options
|
68
|
+
end
|
69
|
+
end
|
70
|
+
end
|
71
|
+
end
|