dependents.info

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

simply add a github action to your repository and use the image link for your repo.

demo

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

watch

quickstart

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`
`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.

embed image

note: the image is only available for repositories that run the github action successfully.

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

github repo:

package id (optional):

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

embed badge

note: the badge is only available for repositories that run the github action successfully.

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 so when the github action submits new data, it will be reflected in the readme automatically.

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.

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