Skip to content

Commit d0a617a

Browse files
CoderrobCoderrob
authored
feat: create composite action to request and display the github rate limit in summary along with console info (#1)
* Initial commit * chore: add DS_STORE to gitignore * chore: patch failure on 0 limits * chore: add copyright and cleanups and documentation
1 parent 32073ec commit d0a617a

File tree

7 files changed

+615
-185
lines changed

7 files changed

+615
-185
lines changed

‎.github/workflows/check-api-limit.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: "Check GitHub API Rate Limit"
2+
3+
on:
4+
workflow_dispatch: {}
5+
6+
jobs:
7+
check-rate-limit:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- name: Checkout Repository
11+
id: checkout-repo
12+
uses: actions/checkout@v4
13+
14+
- name: Run GitHub API Rate Limit Check
15+
id: check-rate-limit
16+
uses: ./
17+
with:
18+
github-token: ${{ github.token }}

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,3 +128,6 @@ dist
128128
.yarn/build-state.yml
129129
.yarn/install-state.gz
130130
.pnp.*
131+
132+
# mac
133+
.DS_STORE

‎LICENSE‎

Lines changed: 183 additions & 183 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 123 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,123 @@
1-
# github-rate-limit-check
2-
GitHub Action to get current GitHub rate limit summary.
1+
# 📊 GitHub API Rate Limit Check
2+
3+
## **Description**
4+
5+
This GitHub Action provides an **automated, real-time check** of your repository’s GitHub API rate limits, giving you **instant visibility** into your API consumption. With detailed reporting and proactive alerts, you can **prevent unexpected disruptions** and **optimize API usage** in your workflows.
6+
7+
Designed for **reliability and clarity**, this composite action:
8+
9+
- Calls the **GitHub Rate Limit API** and extracts real-time usage metrics.
10+
- Formats and logs the results professionally in both **workflow logs** and **GitHub Step Summary**.
11+
- **Warns** when remaining API requests fall below a threshold (default: `100`).
12+
- **Fails fast** when limits are exhausted to avoid unexpected workflow failures.
13+
- **Handles missing data gracefully**, preventing false alarms from disabled or unavailable API endpoints.
14+
15+
Whether you're running frequent automation, managing API-driven integrations, or monitoring GitHub resources, this action ensures you **stay informed and in control** of your API quota.
16+
17+
---
18+
19+
## 🚀 **Why Use This Action?**
20+
21+
✔️ **Prevents Workflow Failures** – Stops workflows from running when API limits are exceeded.
22+
✔️ **Proactive Warnings** – Get alerts when remaining requests drop below a safe threshold.
23+
✔️ **Clear, Professional Reporting** – View a **clean summary table** in GitHub Actions for quick insights.
24+
✔️ **Safe and Robust Handling** – Avoids errors due to missing or unavailable API data.
25+
✔️ **Simple Integration** – Plug it into any workflow with minimal setup.
26+
27+
---
28+
29+
## 📦 **Usage**
30+
31+
### **Workflow Example**
32+
33+
Add the following to your **GitHub Actions workflow** to monitor API usage before running rate-limited tasks.
34+
35+
```yaml
36+
jobs:
37+
check-rate-limit:
38+
name: Check GitHub API Rate Limit
39+
runs-on: ubuntu-latest
40+
steps:
41+
- name: Checkout Repository
42+
id: checkout-repo
43+
uses: actions/checkout@v4
44+
45+
- name: Run GitHub API Rate Limit Check
46+
id: check-rate-limit
47+
uses: coderrob/github-api-rate-limit-check@v1
48+
with:
49+
github-token: ${{ github.token }}
50+
```
51+
52+
---
53+
54+
## 📜 **How It Works**
55+
56+
1. **Fetches Rate Limit Data** → Calls the `https://api.github.com/rate_limit` endpoint.
57+
2. **Parses and Processes Data** → Extracts core, GraphQL, and search API quotas.
58+
3. **Logs Results** → Displays a structured **table** in `GITHUB_STEP_SUMMARY` and console logs.
59+
4. **Triggers Alerts**:
60+
- **Warning** (`⚠️`) if remaining API requests **drop below 100**.
61+
- **Error** (`❌`) if limits are **fully exhausted** (only if that API type is enabled).
62+
5. **Fails the Workflow (if needed)** → Prevents unintended execution when API access is unavailable.
63+
64+
---
65+
66+
## 📊 **Example Output**
67+
68+
### **Console Logs**
69+
70+
```bash
71+
GitHub API Rate Limit Status:
72+
--------------------------------------------
73+
Core API: 85 / 5000 (Resets at 2025-02-20 15:00:00 UTC)
74+
GraphQL: 4500 / 5000 (Resets at 2025-02-20 15:00:00 UTC)
75+
Search: 0 / 30 (Resets at 2025-02-20 15:00:00 UTC)
76+
--------------------------------------------
77+
⚠️ GitHub API Rate Limit is low (85 remaining)!
78+
❌ GitHub Search API Rate Limit has been fully exhausted!
79+
```
80+
81+
---
82+
83+
### 📊 **GitHub API Rate Limit Summary**
84+
85+
| API Type | Remaining | Limit | Reset Time (UTC) |
86+
| ------------ | --------- | ----- | ------------------- |
87+
| **Core API** | **85** | 5000 | 2025-02-20 15:00:00 |
88+
| **GraphQL** | **4500** | 5000 | 2025-02-20 15:00:00 |
89+
| **Search** | **0** | 30 | 2025-02-20 15:00:00 |
90+
91+
⚠️ **Warning:** GitHub API rate limit is low (85 remaining).
92+
❌ **Error:** GitHub Search API rate limit has been fully exhausted.
93+
94+
⏳ API limits reset periodically. Plan requests accordingly.
95+
96+
---
97+
98+
## 🛠 **Inputs**
99+
100+
| Name | Required | Description |
101+
| -------------- | -------- | ------------------------------------------------------------ |
102+
| `github-token` | ✅ Yes | GitHub token used for authentication (`${{ github.token }}`) |
103+
104+
---
105+
106+
## 🎯 **Best Use Cases**
107+
108+
- **Before running API-heavy workflows** (e.g., fetching issue data, triggering GitHub Actions via API).
109+
- **Monitoring CI/CD jobs that rely on GitHub API calls** to avoid failures mid-run.
110+
- **Logging and auditing API usage** across your organization’s GitHub actions.
111+
112+
---
113+
114+
## 🏆 **Take Control of Your GitHub API Usage**
115+
116+
This action gives you the **power to monitor, manage, and prevent API failures before they happen**. Whether you're a solo developer or running large-scale automation, **stay ahead of rate limits and keep your workflows running smoothly**. 🚀
117+
118+
---
119+
120+
### **🔗 Related Resources**
121+
122+
- [GitHub API Rate Limits Docs](https://docs.github.com/en/rest/rate-limit)
123+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)

‎action.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
#
2+
# Copyright 2025 Robert Lindley
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
#
16+
---
17+
author: "Robert Lindley (coderrob)"
18+
name: GitHub API Rate Limit Check
19+
description: This GitHub Action provides an automated, real-time check of your
20+
repository's GitHub API rate limits, giving you instant visibility
21+
into your API consumption. With detailed reporting and proactive
22+
alerts, you can prevent unexpected disruptions and optimize API
23+
usage in your workflows.
24+
25+
branding:
26+
icon: "bar-chart"
27+
color: "blue"
28+
29+
inputs:
30+
github-token:
31+
default: ${{ github.token }}
32+
description: GitHub Token for API authentication
33+
required: false
34+
35+
runs:
36+
using: composite
37+
steps:
38+
- name: Call GitHub Rate Limit API
39+
id: github-rate-limit-api
40+
shell: bash
41+
run: bash "${{ github.action_path }}/scripts/entrypoint.sh" "${{ inputs.github-token }}"

‎scripts/entrypoint.sh‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
#!/bin/bash
2+
3+
#
4+
# Copyright 2025 Robert Lindley
5+
#
6+
# Licensed under the Apache License, Version 2.0 (the "License");
7+
# you may not use this file except in compliance with the License.
8+
# You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
#
18+
19+
set -e # Exit on error
20+
21+
GITHUB_TOKEN=$1
22+
API_URL="https://api.github.com/rate_limit"
23+
24+
echo "Calling GitHub Rate Limit API..."
25+
RESPONSE=$(curl -s -H "Authorization: Bearer $GITHUB_TOKEN" $API_URL)
26+
27+
if [ -z "$RESPONSE" ]; then
28+
echo "::error::Failed to retrieve rate limit data from GitHub API."
29+
exit 1
30+
fi
31+
32+
echo "$RESPONSE" >rate_limit.json
33+
34+
parse_safe() {
35+
local value=$(jq -r "$1 // empty" rate_limit.json)
36+
echo "${value:-0}" # Default to 0 if empty/null
37+
}
38+
39+
RATE_LIMIT=$(parse_safe '.rate.limit')
40+
RATE_REMAINING=$(parse_safe '.rate.remaining')
41+
RATE_RESET=$(parse_safe '.rate.reset')
42+
43+
GRAPHQL_LIMIT=$(parse_safe '.graphql.limit')
44+
GRAPHQL_REMAINING=$(parse_safe '.graphql.remaining')
45+
GRAPHQL_RESET=$(parse_safe '.graphql.reset')
46+
47+
SEARCH_LIMIT=$(parse_safe '.search.limit')
48+
SEARCH_REMAINING=$(parse_safe '.search.remaining')
49+
SEARCH_RESET=$(parse_safe '.search.reset')
50+
51+
format_time() {
52+
if [ "$1" -gt 0 ]; then
53+
date -u -d "@$1" "+%Y-%m-%d %H:%M:%S UTC"
54+
else
55+
echo "N/A"
56+
fi
57+
}
58+
59+
RESET_TIME=$(format_time "$RATE_RESET")
60+
GRAPHQL_RESET_TIME=$(format_time "$GRAPHQL_RESET")
61+
SEARCH_RESET_TIME=$(format_time "$SEARCH_RESET")
62+
63+
echo "GitHub API Rate Limit Status:"
64+
echo "--------------------------------------------"
65+
echo " Core API: $RATE_REMAINING / $RATE_LIMIT (Resets at $RESET_TIME)"
66+
echo " GraphQL: $GRAPHQL_REMAINING / $GRAPHQL_LIMIT (Resets at $GRAPHQL_RESET_TIME)"
67+
echo " Search: $SEARCH_REMAINING / $SEARCH_LIMIT (Resets at $SEARCH_RESET_TIME)"
68+
echo "--------------------------------------------"
69+
70+
# Core API Limits
71+
if [ "$RATE_LIMIT" -gt 0 ] && [ "$RATE_REMAINING" -le 0 ]; then
72+
echo "::error::❌ GitHub API Rate Limit has been fully exhausted!"
73+
exit 1
74+
elif [ "$RATE_LIMIT" -gt 0 ] && [ "$RATE_REMAINING" -lt 100 ]; then
75+
echo "::warning::⚠️ GitHub API Rate Limit is low ($RATE_REMAINING remaining)!"
76+
fi
77+
78+
# GraphQL Limits
79+
if [ "$GRAPHQL_LIMIT" -gt 0 ] && [ "$GRAPHQL_REMAINING" -le 0 ]; then
80+
echo "::error::❌ GitHub GraphQL API Rate Limit has been fully exhausted!"
81+
exit 1
82+
elif [ "$GRAPHQL_LIMIT" -gt 0 ] && [ "$GRAPHQL_REMAINING" -lt 100 ]; then
83+
echo "::warning::⚠️ GitHub GraphQL API Rate Limit is low ($GRAPHQL_REMAINING remaining)!"
84+
fi
85+
86+
# Search Limits
87+
if [ "$SEARCH_LIMIT" -gt 0 ] && [ "$SEARCH_REMAINING" -le 0 ]; then
88+
echo "::error::❌ GitHub Search API Rate Limit has been fully exhausted!"
89+
exit 1
90+
elif [ "$SEARCH_LIMIT" -gt 0 ] && [ "$SEARCH_REMAINING" -lt 100 ]; then
91+
echo "::warning::⚠️ GitHub Search API Rate Limit is low ($SEARCH_REMAINING remaining)!"
92+
fi
93+
94+
# GitHub Step Summary
95+
echo "# :bar_chart: GitHub API Rate Limit Summary" >>$GITHUB_STEP_SUMMARY
96+
echo "" >>$GITHUB_STEP_SUMMARY
97+
echo "| API Type | Remaining | Limit | Reset Time (UTC) |" >>$GITHUB_STEP_SUMMARY
98+
echo "|-----------|----------|-------|------------------|" >>$GITHUB_STEP_SUMMARY
99+
echo "| Core API | $RATE_REMAINING | $RATE_LIMIT | $RESET_TIME |" >>$GITHUB_STEP_SUMMARY
100+
echo "| GraphQL | $GRAPHQL_REMAINING | $GRAPHQL_LIMIT | $GRAPHQL_RESET_TIME |" >>$GITHUB_STEP_SUMMARY
101+
echo "| Search | $SEARCH_REMAINING | $SEARCH_LIMIT | $SEARCH_RESET_TIME |" >>$GITHUB_STEP_SUMMARY
102+
echo "" >>$GITHUB_STEP_SUMMARY
103+
104+
if [ "$RATE_LIMIT" -gt 0 ] && [ "$RATE_REMAINING" -lt 100 ]; then
105+
echo "⚠️ **Warning:** GitHub API rate limit is low ($RATE_REMAINING remaining)." >>$GITHUB_STEP_SUMMARY
106+
fi
107+
if [ "$GRAPHQL_LIMIT" -gt 0 ] && [ "$GRAPHQL_REMAINING" -lt 100 ]; then
108+
echo "⚠️ **Warning:** GitHub GraphQL API rate limit is low ($GRAPHQL_REMAINING remaining)." >>$GITHUB_STEP_SUMMARY
109+
fi
110+
if [ "$SEARCH_LIMIT" -gt 0 ] && [ "$SEARCH_REMAINING" -lt 100 ]; then
111+
echo "⚠️ **Warning:** GitHub Search API rate limit is low ($SEARCH_REMAINING remaining)." >>$GITHUB_STEP_SUMMARY
112+
fi
113+
114+
echo "⏳ API limits reset hourly. Plan requests accordingly." >>$GITHUB_STEP_SUMMARY

0 commit comments

Comments
 (0)