dependents.info

easily generate an image of github network dependents to showcase in your project's readme.md file.

simply use the embed codes, or optionally add a github action for customizations, in your repository.

demo

here's a demo of the generated shields.io badge and the image:

Total network dependents badge for GitHub repo gouravkhunger/jekyll-auto-authors

Network dependents preview for GitHub repo gouravkhunger/jekyll-auto-authors

watch

quickstart

enter your github repository name in the format owner/repo to generate copyable embed codes.

github repo:

package id (optional):

embed image

note: to customize the frequency of image re-generation, please setup the github action.

paste this code anywhere in the readme and the auto-generated dependents image will be embedded!

by default, the image is generated from the first few dependents. use the github action to control this. for example, showcase only the repositories with the most stars.

embed badge

note: to customize the frequency of badge re-generation, please setup the github action.

available query params (optional):

logo: icon name from simple-icons.
label: override the default label "dependents".
color: hex, rgb, rgba, hsl, hsla or css named color.
logoColor: hex, rgb, rgba, hsl, hsla or css named color.
labelColor: hex, rgb, rgba, hsl, hsla or css named color.
style: [flat (default), flat-square, plastic, for-the-badge, social]

usage: /badge?color=red&style=flat-square

paste this code where you want the badge to appear in the readme.

the badge and the image are self updating. they are generated on fetch requests and cached for a period of 7 days.

when using the github action, they update as soon as new data is ingested.

note: in addition to cloudflare's cache lasting up to a day, the image could be cached by github for an extended 7 day period. please refer to the docs on how to manually purge it if required.

github action

you can use the service with limited features even without setting up the github action.

add this file to your repository's .github/workflows folder.

dependents.yml

once you push this file, the action will process the dependents for the repository and the backend will generate the badge and the image.

tip: instead of running the action on push, you can use a cron job to schedule the action.

configuration (optional)

add the following options to your dependents.yml file if you want to customize the action's behavior:

option	type	description	default
`max-pages`	`number`	number of network dependents pages to process (max: 100).	`50`
`force-run`	`boolean`	force submit data to the backend. only affects forked repositories.	`false`
`package-id`	`string`	use if repo hosts multiple packages. action processes only one at a time.	`""`
`unique-owners`	`boolean`	disables duplicate users in the generated image.	`true`
`exclude-owner`	`boolean`	exclude repos from the same owner that depend on this repository.	`true`
`exclude-users`	`string`	comma-separated list of users to exclude from the generated image.	`""`
`upload-artifacts`	`boolean`	whether to upload the outputs as action's build artifacts.	`true`

why github action?

the github action does the heavy lifting of fetching the dependents from your repository's network dependents page.

doing it in a github action makes it much easier to do that from their hosted runners, avoid ip bans, and adhere to the purpose of "archival" of public information as per the tos.

the permission id-token with value write is required for the action to request a github oidc token at the runtime which is then sent to the backend along with the scraped data.

while the id-token permission is required to request the oidc token, it in itself is not a security concern to your repository. here's more info from the github docs:

You won't be able to request the OIDC JWT ID token if the permissions for id-token is not set to write, however this value doesn't imply granting write access to any resources, only being able to fetch and set the OIDC token for an action or step to enable authenticating with a short-lived access token.

the backend uses the token to verify the repository claim directly from github to compare where the data is coming from. mismatched fields will fail the request.

this check ensures that the data backend accepts from a repository comes from it's github action itself. only the action can alter the data in production.

multiple packages

if your repository hosts multiple packages, you can use the package-id option to specify which package to process. other packages can be processed by adding new steps in the same workflow file.

the package-id string can be found by going to repository's home page > insights > dependency graph > dependents > select package > copy the text after ?package_id= in the url.

the same package id should be added to the end of every dependents.info url embedded in the readme with ?id=idHere