backage

It's all part and parcel

---

Ever wish you could show npm, gem, mvn, Gradle, NuGet, or GHCR badges for GitHub Packages? Or just query for the download counts? This endpoint makes that possible, using only free GitHub resources; the API doesn't, and has never, exposed the public metadata that other registries provide.

Getting Started

If this is ipitio/backage, all you have to do is star the repo to get your public packages added! The service's circular priority queue will update the closed-loop system with them within the next few hours. Additionally watching and forking the repo, and following the owner, are ways to increase their priority. Yes, I know, but these are the graphs GitHub has available.

Warning

Ensure your profile is public so that this repo can see your packages.

Otherwise, if this is a fork, you'd prefer an alternative method, or your packages weren't added to the index after a day, enter the case-sensitive name of each missing user or organization on a new line at the top of the queue, owners.txt, here and make a pull request. Don't worry -- while my Contribution Graph is an uptime monitor of sorts, yours won't be. Run bkg workflow-update --help in the image for the available update options; the common ones are shown in Self-Host below.

Tip

You only need to add names to the queue; IDs are fetched as needed and entries are removed once processed.

New packages may not be added until all existing ones are refreshed; you should also create an independent instance that'll update faster and more frequently. Simply fork just the master branch, choose one of the following options, and use the Alternative URL when it changes. This centralized repo will then serve as a backup for all subsets of packages not in optout.txt.

Important

Your own packages will be picked up automatically! If you need to edit owners.txt, do so after the first run.

Forks that merge upstream changes locally should run bkg configure-fork-merge . once in each clone. Ordinary merges will then retain that deployment's owners.txt, optout.txt, and generated README.md while accepting templates, contributor documentation, and other upstream changes. The setting is clone-local: use a merge rather than a rebase, and do not use GitHub's Sync fork button for an update that changes any of these files.

With Actions

You can use GitHub-hosted runners or your own.

1. Enable Actions from its tab
2. Enable all disabled workflows

Self-Host

This is an example for systemd; adapt it to your needs. Please note:

• Docker needs to be installed
• GITHUB_TOKEN can be $(gh auth token)
• -m 0 ensures only the public packages of the owners you've added are updated (default)
  • You'll need the proper permissions to update private packages
• -d 0 allows everything to be updated in one go
  • A graceful restart is initiated every 4 hours by default

echo"[Unit]Description=Run BackageAfter=network.targetStartLimitIntervalSec=0[Service]Type=simpleRestart=alwaysRestartSec=5ExecStart=/usr/bin/sh -c ' \\ GITHUB_TOKEN=<PAT> ;\\ GITHUB_OWNER=<username> ;\\ GITHUB_REPO=backage ;\\ GITHUB_BRANCH=master ;\\ BKG_PATH=\$GITHUB_REPO/\$GITHUB_BRANCH ;\\ mkdir -p /opt/\$BKG_PATH ;\\ docker run -v /opt/\$BKG_PATH:/app \\ --env-file <(env | grep GITHUB) \\ ghcr.io/\$GITHUB_OWNER/\${BKG_PATH////:} \\ bkg workflow-update -C /app -m 0 -d 0'[Install]WantedBy=multi-user.target"| sudo tee /etc/systemd/system/bkg.service
sudo systemctl daemon-reload
sudo systemctl enable --now bkg

The Endpoint

https://ipitio.github.io/backage/OWNER/[REPO/[PACKAGE]].FORMAT

Once the packages you're interested in have been added, replace the parameters with their respective values, scoping to your parsing needs, then access the latest data however you want. The format can be either json or xml.

Note

Package endpoints keep detailed version data. Owner and repo aggregate endpoints bound their version detail so large self-hosted indexes can still finish JSON/XML publication. BKG_OWNER_ARRAY_MAX_BYTES defaults to 35000000; BKG_OWNER_ARRAY_VERSION_LIMIT can force a fixed per-package aggregate version limit, and negative values keep full version arrays. DB-backed aggregates estimate a safe per-package version limit from the database before rendering once; BKG_OWNER_ARRAY_DB_VERSION_LIMIT can force a fixed DB-backed aggregate limit, and BKG_OWNER_ARRAY_DB_FALLBACK_VERSION_LIMIT defaults to 2 if estimation is unavailable. JSON/XML trimming uses BKG_JSON_XML_MAX_BYTES (50000000) and BKG_JSON_XML_HARD_MAX_BYTES (100000000).

Note

Use something like shields.io/json or shields.io/xml to make badges like this one. You'll need the latter to evaluate expressions, like filters (issue).

Available Properties

Package

Property	Type	Description
owner_id	number	The ID of the owner
owner_type	string	The type of owner (e.g. users)
package_type	string	The type of package (e.g. container)
owner	string	The owner of the package
repo	string	The repository of the package
package	string	The package name
date	string	The most recent date the package was refreshed
size	string	Formatted best size from the newest sized version
versions	string	Formatted count of all versions recently tracked
tagged	string	Formatted count of all tagged versions recently tracked
owner_rank	string	Formatted rank by downloads within the owner
repo_rank	string	Formatted rank by downloads within the repository
downloads	string	Formatted count of all downloads
downloads_month	string	Formatted count of all downloads in the last month
downloads_week	string	Formatted count of all downloads in the last week
downloads_day	string	Formatted count of all downloads in the last day
raw_size	number	Best size from the newest sized version, in bytes
raw_versions	number	Count of versions ever tracked
raw_tagged	number	Count of tagged versions ever tracked
raw_owner_rank	number	Rank by downloads within the owner
raw_repo_rank	number	Rank by downloads within the repository
raw_downloads	number	Count of all downloads
raw_downloads_month	number	Count of all downloads in the last month
raw_downloads_week	number	Count of all downloads in the last week
raw_downloads_day	number	Count of all downloads in the last day
version	object array	The versions of the package (see below)

Version

Property	Type	Description
id	number	The ID of the version
name	string	The version name
date	string	The most recent date the version was refreshed
newest	boolean	Whether the version is the newest
latest	boolean	Whether the version is the newest tagged
size	string	Formatted best available size of the version
downloads	string	Formatted count of downloads
downloads_month	string	Formatted count of downloads in the last month
downloads_week	string	Formatted count of downloads in the last week
downloads_day	string	Formatted number of downloads in the last day
raw_size	number	Best available size of the version, in bytes
raw_downloads	number	Count of downloads
raw_downloads_month	number	Count of downloads in the last month
raw_downloads_week	number	Count of downloads in the last week
raw_downloads_day	number	Count of downloads in the last day
tags	string array	The tags of the version

Query Syntax

JSON

You can query a package for its properties, like size or version:

$.PROPERTY

$.size

Versions may be filtered in and tags out:

$.version[FILTER].PROPERTY

$.version[?(@.latest)].tags[?(@!="latest")]

As can packages in owner[/repo]/.json files:

$.[FILTER].PROPERTY

XML

You can query a package for its properties, like size or version:

//PROPERTY

//size

Versions can be filtered in and tags out:

//version[FILTER]/PROPERTY

//version[./latest[.="true"]]/tags[.!="latest"]

As can packages in owner[/repo]/.xml files:

//package[FILTER]/PROPERTY

Alternative URL

https://github.com/pkgforge-dev/backage/raw/index/OWNER/[REPO/[PACKAGE]].FORMAT

The endpoint is also available here! This will change to your fork once it updates.

Documentation

• Contributing

Bring Your Own JSON

https://ipitio.github.io/backage?json=https://URL/ENCODED/JSON

While this doesn't directly work with Shields, you can BYOJ to convert into XML. Try it out in your browser:

https://ipitio.github.io/backage?json=https://raw.githubusercontent.com/pkgforge-dev/backage/index/.json