Octokit plugin for GitHub’s recommended request throttling
Installations
npm install @octokit/plugin-throttlingDeveloper Guide
Typescript
Yes
Module System
ESM
Min. Node Version
>= 18
Node Version
22.12.0
NPM Version
10.9.2
Score
91.6
Supply Chain
99.5
Quality
92.8
Maintenance
100
Vulnerability
100
License
Releases
Contributors
Languages
TypeScript (92.42%)
JavaScript (7.58%)
Developer
octokit
Download Statistics
Total Downloads
156,148,314
Last Day
380,626
Last Week
1,782,104
Last Month
8,051,877
Last Year
91,183,249
GitHub Statistics
115 Stars
829 Commits
36 Forks
10 Watching
6 Branches
30 Contributors
Maintainers
Package Meta Information
Latest Version
9.4.0
Package Id
@octokit/plugin-throttling@9.4.0
Unpacked Size
38.50 kB
Size
9.11 kB
File Count
16
NPM Version
10.9.2
Node Version
22.12.0
Publised On
08 Jan 2025
Total Downloads
Cumulative downloads
Total Downloads
156,148,314
Last day
-11.7%
380,626
Compared to previous day
Last week
-16.6%
1,782,104
Compared to previous week
Last month
10.2%
8,051,877
Compared to previous month
Last year
95.3%
91,183,249
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
2
Peer Dependencies
1
plugin-throttling.js
Octokit plugin for GitHub’s recommended request throttling
Implements all recommended best practices to prevent hitting secondary rate limits.
Usage
| Browsers |
Load
|
|---|---|
| Node |
Install with
|
[!IMPORTANT] As we use conditional exports, you will need to adapt your
tsconfig.jsonby setting"moduleResolution": "node16", "module": "node16".See the TypeScript docs on package.json "exports".
See this helpful guide on transitioning to ESM from @sindresorhus
The code below creates a "Hello, world!" issue on every repository in a given organization. Without the throttling plugin it would send many requests in parallel and would hit rate limits very quickly. But the @octokit/plugin-throttling slows down your requests according to the official guidelines, so you don't get blocked before your quota is exhausted.
The throttle.onSecondaryRateLimit and throttle.onRateLimit options are required. Return true to automatically retry the request after retryAfter seconds.
1const MyOctokit = Octokit.plugin(throttling); 2 3const octokit = new MyOctokit({ 4 auth: `secret123`, 5 throttle: { 6 onRateLimit: (retryAfter, options, octokit, retryCount) => { 7 octokit.log.warn( 8 `Request quota exhausted for request ${options.method} ${options.url}`, 9 ); 10 11 if (retryCount < 1) { 12 // only retries once 13 octokit.log.info(`Retrying after ${retryAfter} seconds!`); 14 return true; 15 } 16 }, 17 onSecondaryRateLimit: (retryAfter, options, octokit) => { 18 // does not retry, only logs a warning 19 octokit.log.warn( 20 `SecondaryRateLimit detected for request ${options.method} ${options.url}`, 21 ); 22 }, 23 }, 24}); 25 26async function createIssueOnAllRepos(org) { 27 const repos = await octokit.paginate( 28 octokit.repos.listForOrg.endpoint({ org }), 29 ); 30 return Promise.all( 31 repos.map(({ name }) => 32 octokit.issues.create({ 33 owner, 34 repo: name, 35 title: "Hello, world!", 36 }), 37 ), 38 ); 39}
Pass { throttle: { enabled: false } } to disable this plugin.
Clustering
Enabling Clustering support ensures that your application will not go over rate limits across Octokit instances and across Nodejs processes.
First install either redis or ioredis:
# NodeRedis (https://github.com/NodeRedis/node_redis)
npm install --save redis
# or ioredis (https://github.com/luin/ioredis)
npm install --save ioredis
Then in your application:
1import Bottleneck from "bottleneck";
2import Redis from "redis";
3
4const client = Redis.createClient({
5 /* options */
6});
7const connection = new Bottleneck.RedisConnection({ client });
8connection.on("error", err => console.error(err));
9
10const octokit = new MyOctokit({
11 auth: 'secret123'
12 throttle: {
13 onSecondaryRateLimit: (retryAfter, options, octokit) => {
14 /* ... */
15 },
16 onRateLimit: (retryAfter, options, octokit) => {
17 /* ... */
18 },
19
20 // The Bottleneck connection object
21 connection,
22
23 // A "throttling ID". All octokit instances with the same ID
24 // using the same Redis server will share the throttling.
25 id: "my-super-app",
26
27 // Otherwise the plugin uses a lighter version of Bottleneck without Redis support
28 Bottleneck
29 }
30});
31
32// To close the connection and allow your application to exit cleanly:
33await connection.disconnect();To use the ioredis library instead:
1import Redis from "ioredis"; 2const client = new Redis({ 3 /* options */ 4}); 5const connection = new Bottleneck.IORedisConnection({ client }); 6connection.on("error", (err) => console.error(err));
Options
| name | type | description |
|---|---|---|
options.retryAfterBaseValue
|
Number
|
Number of milliseconds that will be used to multiply the time to wait based on `retry-after` or `x-ratelimit-reset` headers. Defaults to 1000
|
options.fallbackSecondaryRateRetryAfter
|
Number
|
Number of seconds to wait until retrying a request in case a secondary rate limit is hit and no retry-after header was present in the response. Defaults to 60
|
options.connection
|
Bottleneck.RedisConnection
| A Bottleneck connection instance. See Clustering above. |
options.id
|
string
|
A "throttling ID". All octokit instances with the same ID using the same Redis server will share the throttling. See Clustering above. Defaults to no-id.
|
options.Bottleneck
|
Bottleneck
| Bottleneck constructor. See Clustering above. Defaults to `bottleneck/light`. |
LICENSE
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
18 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
all changesets reviewed
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
packaging workflow detected
Details
- Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:14
Reason
SAST tool is run on all commits
Details
- Info: SAST configuration detected: CodeQL
- Info: all commits (30) are checked with a SAST tool
Reason
security policy file detected
Details
- Info: security policy file detected: SECURITY.md:1
- Info: Found linked content: SECURITY.md:1
- Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy
- Info: Found text in security policy: SECURITY.md:1
Reason
1 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-vg6x-rcgg-rjx6
Reason
dependency not pinned by hash detected -- score normalized to 5
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:59: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:72: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/release.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/release.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/test.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/test.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/test.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/test.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/update-prettier.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/update-prettier.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/update-prettier.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/update.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/update.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/update.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/update.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/update.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/plugin-throttling.js/update.yml/main?enable=pin
- Info: 0 out of 14 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 2 third-party GitHubAction dependencies pinned
- Info: 5 out of 5 npmCommand dependencies pinned
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:28
- Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:29
- Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1
- Warn: topLevel 'contents' permission set to 'write': .github/workflows/release.yml:8
- Warn: no topLevel permission defined: .github/workflows/test.yml:1
- Warn: no topLevel permission defined: .github/workflows/update-prettier.yml:1
- Warn: no topLevel permission defined: .github/workflows/update.yml:1
- Info: no jobLevel write permissions found
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Score
7.6
/10
Last Scanned on 2025-01-27
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More