Collect information about dependencies between a github repo and other repositories.
GitHub API does not allow to collect information about package usage (Used by on home, Dependents in insights section)
This package uses GitHub HTML to collect dependents information and can:
- Automate all the actions below using a simple GitHub Action !
- Output as text
- Output as json (including shields.io markdown badges)
- Generate summary markdown file
- Optionally add an AI-generated usage summary (via
litellm) when an LLM API key is present - Update existing markdown by inserting Used by badge within tags
<!-- gh-dependents-info-used-by-start --> [](https://github.com/nvuillam/github-dependents-info/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->
- Handle multiple repositories packages
- Filter results using minimum stars or by repository owner
- Keep huge ecosystems manageable with pagination controls (
--max-scraped-pages,--pagination/--no-pagination,--page-size) - Fetch dependents faster thanks to asynchronous
httpxrequests and parallelized page scraping
Badges example
&message=11&color=informational&logo=slickpic)
&message=4&color=informational&logo=slickpic)
&message=56&color=informational&logo=slickpic)
JSON output
Note: when AI usage summary is enabled and an LLM API key is present, the JSON output also includes llm_summary.
{
"all_public_dependent_repos": [
{
"name": "CIT-SeniorDesign/CIT-SeniorDesign.github.io",
"stars": 0
},
{
"name": "Moaz-Adel/Jobsity-Challenge",
"stars": 0
},
{
"name": "Moaz-Adel/automation-exercise-cypress",
"stars": 0
},
{
"name": "RecuencoJones/vscode-groovy-lint-issue",
"stars": 0
},
{
"name": "aboe026/data-structures",
"stars": 0
},
{
"name": "aboe026/shields.io-badge-results",
"stars": 0
},
{
"name": "aboe026/software-update-checker",
"stars": 2
},
{
"name": "katalon-labs/katalon-recorder-extension",
"stars": 0
},
{
"name": "mashafrancis/sa-jenkins",
"stars": 0
},
{
"name": "nvuillam/vscode-groovy-lint",
"stars": 52
},
{
"name": "run2cmd/dotfiles",
"stars": 2
}
],
"packages": [
{
"id": null,
"name": "nvuillam/npm-groovy-lint",
"url": "https://github.com/nvuillam/npm-groovy-lint/network/dependents",
"public_dependent_stars": 56,
"public_dependents": [
{
"name": "CIT-SeniorDesign/CIT-SeniorDesign.github.io",
"stars": 0
},
{
"name": "Moaz-Adel/Jobsity-Challenge",
"stars": 0
},
{
"name": "Moaz-Adel/automation-exercise-cypress",
"stars": 0
},
{
"name": "RecuencoJones/vscode-groovy-lint-issue",
"stars": 0
},
{
"name": "aboe026/data-structures",
"stars": 0
},
{
"name": "aboe026/shields.io-badge-results",
"stars": 0
},
{
"name": "aboe026/software-update-checker",
"stars": 2
},
{
"name": "katalon-labs/katalon-recorder-extension",
"stars": 0
},
{
"name": "mashafrancis/sa-jenkins",
"stars": 0
},
{
"name": "nvuillam/vscode-groovy-lint",
"stars": 52
},
{
"name": "run2cmd/dotfiles",
"stars": 2
}
],
"public_dependents_number": 11,
"private_dependents_number": 4,
"total_dependents_number": 15,
"badges": {
"total": "[](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
"public": "[&message=11&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
"private": "[&message=4&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
"stars": "[&message=56&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)"
}
}
],
"total_dependents_number": 15,
"public_dependents_number": 11,
"private_dependents_number": 4,
"public_dependents_stars": 56,
"badges": {
"total": "[](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
"public": "[&message=11&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
"private": "[&message=4&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
"stars": "[&message=56&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)"
}
}
Markdown output for single package
# Dependents stats for nvuillam/npm-groovy-lint
## Package nvuillam/npm-groovy-lint
[](https://github.com/nvuillam/npm-groovy-lint/network/dependents)
[&message=11&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)
[&message=4&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)
[&message=56&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)
| Repository | Stars |
|:--------------------------------------------------------------------------------------------------------------|------:|
| [CIT-SeniorDesign/CIT-SeniorDesign.github.io](https://github.com/CIT-SeniorDesign/CIT-SeniorDesign.github.io) | 0 |
| [Moaz-Adel/Jobsity-Challenge](https://github.com/Moaz-Adel/Jobsity-Challenge) | 0 |
| [Moaz-Adel/automation-exercise-cypress](https://github.com/Moaz-Adel/automation-exercise-cypress) | 0 |
| [RecuencoJones/vscode-groovy-lint-issue](https://github.com/RecuencoJones/vscode-groovy-lint-issue) | 0 |
| [aboe026/data-structures](https://github.com/aboe026/data-structures) | 0 |
| [aboe026/shields.io-badge-results](https://github.com/aboe026/shields.io-badge-results) | 0 |
| [aboe026/software-update-checker](https://github.com/aboe026/software-update-checker) | 2 |
| [katalon-labs/katalon-recorder-extension](https://github.com/katalon-labs/katalon-recorder-extension) | 0 |
| [mashafrancis/sa-jenkins](https://github.com/mashafrancis/sa-jenkins) | 0 |
| [nvuillam/vscode-groovy-lint](https://github.com/nvuillam/vscode-groovy-lint) | 52 |
| [run2cmd/dotfiles](https://github.com/run2cmd/dotfiles) | 2 |
_Generated by [github-dependents-info](https://github.com/nvuillam/github-dependents-info)_Note: If your repository packages have millions of dependents, running github-dependent-infos could take hours, as it works by browsing and scraping HTML pages returned by GitHub. For example, angular/angular dependents did run during several hours !
pip install -U github-dependents-infoor install with Poetry
poetry add github-dependents-info github-dependents-info [OPTIONS]| Parameter | Type | Description |
|---|---|---|
| --repo | String | Repository. Example: oxsecurity/megalinter |
| -b --badgemarkdownfile |
String | (optional) Path to markdown file where to insert/update Used by badge (must contain tags <!-- gh-dependents-info-used-by-start --> … <!-- gh-dependents-info-used-by-end -->) |
| -s --sort |
String | (optional) Sort order: name (default) or stars |
| -x --minstars |
String | (optional) If set, filters repositories to keep only those with more than X stars |
| -m --markdownfile |
String | (optional) Output markdown file file |
| -d --docurl |
String | (optional) Hyperlink to use when clicking on badge markdown file badge. (Default: link to markdown file) |
| -p --mergepackages |
String | (optional) In case of multiple packages, merge their stats in a single one in markdown and json output |
| -j --json |
String | (optional) Output in json format |
| -u --owner |
String | (optional) If set, filters repositories to keep only those owned by the specified user/organization |
| -n --max-scraped-pages |
Integer | (optional) Maximum number of GitHub pages to scrape per package (0 uses all available pages) |
| --pagination --no-pagination |
Boolean | (optional) Enable (default) or disable pagination when writing markdown output |
| --page-size | Integer | (optional) Number of repositories per markdown page when pagination is enabled (default: 500) |
| --llm-summary --no-llm-summary |
Boolean | (optional) Generate an AI usage summary in markdown output when an LLM API key is present (default: enabled) |
| --llm-model | String | (optional) LiteLLM model to use for the summary. If not set, a lightweight model is selected based on the detected API key provider |
| --llm-max-repos | Integer | (optional) Max dependent repos included in the summary prompt payload (default: 500) |
| --llm-max-words | Integer | (optional) Max words for the generated summary (default: 300) |
| --llm-timeout | Float | (optional) Timeout (seconds) for the summary LLM call (default: 120) |
| -v --version |
Boolean | (optional) Displays version of github-dependents-info |
| --verbose | Boolean | (optional) Verbose output |
Badge tags example (the tool replaces everything between the markers):
<!-- gh-dependents-info-used-by-start -->
[](https://github.com/nvuillam/github-dependents-info/blob/main/docs/github-dependents-info.md)
<!-- gh-dependents-info-used-by-end -->-
Text output
github-dependents-info --repo nvuillam/npm-groovy-lint -
JSON output
github-dependents-info --repo nvuillam/npm-groovy-lint --json -
Insert/Update Used by markdown badge within an existing markdown file containing tags
<!-- gh-dependents-info-used-by-start --> [](https://github.com/nvuillam/github-dependents-info/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->github-dependents-info --repo nvuillam/npm-groovy-lint --badgemarkdownfile ./README.md -
Build markdown file with dependent repos (single package), sorted by name
github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --verbose -
Build markdown file with dependent repos (single package), with minimum 10 stars
github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --minstars 10 --verbose -
Build markdown file with dependent repos (multiple package), sorted by stars
github-dependents-info --repo oxsecurity/megalinter --markdownfile ./docs/package-usage.md --sort stars --verbose -
Build markdown file with dependent repos (multiple package), with merged list of packages in output markdown
github-dependents-info --repo oxsecurity/megalinter --markdownfile ./docs/package-usage.md --sort stars --mergepackages --verbose -
Limit scraping to repositories owned by a specific organization and cap pagination to 5 pages per package
github-dependents-info --repo oxsecurity/megalinter --owner oxsecurity --max-scraped-pages 5 --verbose
-
Generate paginated markdown with 250 repositories per page (use
--no-paginationto force a single file)github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --page-size 250 --mergepackages
-
Disable AI usage summary generation
github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --no-llm-summary
-
Force a specific LiteLLM model for the summary
github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --llm-model gpt-4o-mini
-
Generate markdown with AI summary using
OPENAI_API_KEYGEMINI_API_KEY=YOUR_KEY github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --llm-model gemini-3-flash-preview
If an LLM API key is detected in the environment (for example OPENAI_API_KEY), the tool will call a lightweight model (via litellm) to generate a short usage summary and include it in the generated markdown.
-
Supported provider env vars (most common):
- OpenAI:
OPENAI_API_KEY - Azure OpenAI:
AZURE_OPENAI_API_KEY - Anthropic:
ANTHROPIC_API_KEY - Google Gemini:
GEMINI_API_KEY(orGOOGLE_API_KEY) - Mistral:
MISTRAL_API_KEY - Cohere:
COHERE_API_KEY - Groq:
GROQ_API_KEY
- OpenAI:
-
Disable with
--no-llm-summary(or env varGITHUB_DEPENDENTS_INFO_LLM_SUMMARY=false) -
Override model with
--llm-model(or env varGITHUB_DEPENDENTS_INFO_LLM_MODEL/LITELLM_MODEL) -
Adjust max summary length with
--llm-max-words(or env varGITHUB_DEPENDENTS_INFO_LLM_MAX_WORDS) -
The summary is cached in
--csvdirectory(filellm_summary_<repo>.json) and reused on subsequent runs
Allow GitHub Actions to create Pull Requests in Settings > Actions > General
Create a file .github/workflows/github-dependents-info.yml in your repository with the following YAML content.
If will generate a new Pull Request (or replace the pending one) every time the usage stats will have changed :)
Don't forget to add tags <!-- gh-dependents-info-used-by-start --> [](https://github.com/nvuillam/github-dependents-info/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end --> in your README.md, at the end of another badge line if you want github-dependents-info to replace its content automatically.
# GitHub Dependents Info workflow
# More info at https://github.com/nvuillam/github-dependents-info/
name: GitHub Dependents Info
# Let by default
on:
# On manual launch
workflow_dispatch:
# On every push on selected branches (usually just main)
push:
branches: [main,master,setup-gdi]
# Scheduled interval: Use CRON format https://crontab.guru/
schedule:
- cron: "0 0 * * 0" # Every sunday at midnight
permissions: read-all
concurrency:
group: ${{ github.ref }}-${{ github.workflow }}
cancel-in-progress: true
jobs:
build:
name: GitHub Dependents Info
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
# Git Checkout
- name: Checkout Code
uses: actions/checkout@v6
with:
token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
fetch-depth: 0
# Collect data & generate markdown
- name: GitHub Dependents Info
uses: nvuillam/github-dependents-info@v1.6.3 # If you want to always have the latest version, you can use nvuillam/github-dependents-info@main :)
# See documentation for variables details: https://github.com/nvuillam/github-dependents-info?tab=readme-ov-file#%EF%B8%8F-usage
with:
repo: ${{ github.repository }}
outputrepo: ${{ github.repository }}
# markdownfile: docs/github-dependents-info.md
# badgemarkdownfile: README.md
# sort: stars
# minstars: "0"
# llm-summary: "carview.php?tsp=true" # set to "false" to disable AI usage summary
# llm-model: "" # optional: override LiteLLM model (example: gpt-4o-mini, gemini-3-flash-preview)
# llm-max-repos: "500" # optional: cap repos sent to the summary prompt
# llm-max-words: "250" # optional: cap summary length
# llm-timeout: "120" # optional: timeout (seconds) for the LLM call
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# To enable the AI usage summary, provide one of the supported provider API keys, for example:
# OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
# GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
# Workaround for git issues
- name: Prepare commit
run: sudo chown -R $USER:$USER .
# Create pull request
- name: Create Pull Request
id: cpr
uses: peter-evans/create-pull-request@v8
with:
token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
branch: github-dependents-info-auto-update
commit-message: "[GitHub Dependents Info] Updated markdown file(s)"
delete-branch: true
title: "[GitHub Dependents Info] Updated markdown file"
body: "_Generated with [github-dependents-info](https://github.com/nvuillam/github-dependents-info), by [Nicolas Vuillamy](https://github.com/nvuillam)_"
labels: documentation
- name: Create PR output
run: |
echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"This project is licensed under the terms of the MIT license. See LICENSE for more details.
This package has been inspired by stackexchange post How to use GitHub API to get a repository's dependents information in GitHub?
This project was generated with python-package-template