Github Packages: Ruby Gem Version

[voltechs]

📋 Description

This badge would display the latest version of a Ruby gem published to GitHub Packages.

Which service is this badge for: GitHub Packages (Ruby gems registry)

What sort of information should this badge show: The latest version number of a Ruby gem from GitHub Packages, similar to existing badges for other package managers.

Proposed URL format:
https://img.shields.io/github/ruby-package/v/{owner}/{package}

Example:

• https://img.shields.io/github/ruby-package/v/twilightcoders/gemplate → displays "v0.0.1"
• https://img.shields.io/github/ruby-package/v/twilightcoders/sudo → displays "v0.4.0"

Related:

• version of gem read dynamically from Gemfile #6789

🔗 Data

Data source: GitHub Packages API endpoint for Ruby gems:
https://api.github.com/orgs/{owner}/packages?package_type=rubygems

Is there a public API: Yes, GitHub's REST API provides package information including versions. The endpoint returns package metadata including all published versions, allowing retrieval of the latest version.

This would complement the existing GitHub Packages badges for other package types (npm, Docker, etc.) and provide consistency across the GitHub Packages ecosystem.

GitHub Packages API endpoint:
https://api.github.com/orgs/{owner}/packages?package_type=rubygems

The API returns package metadata including version information. The latest version can be extracted from the package versions array.

🎤 Motivation

Many organizations and developers are migrating from public package registries to GitHub Packages for better security, access control, and integration with their existing GitHub workflows. However, there's currently no way to display version badges for Ruby gems hosted on GitHub Packages, creating an inconsistency in documentation and project visibility.

Specific use cases:

• Private/internal gems: Organizations publishing internal Ruby gems to GitHub Packages need version badges for their internal documentation and README files
• Security-conscious projects: Teams using GitHub Packages for enhanced security and access control still want to display current version information publicly
• Consistency across package types: GitHub Packages already supports npm, Docker, and other package types in shields.io - Ruby gems are a notable gap
• Migration from public registries: Projects moving from RubyGems.org to GitHub Packages lose the ability to display version badges, hindering adoption
• Enterprise workflows: Companies using GitHub Enterprise with GitHub Packages need version badges for their internal project dashboards and documentation

This feature would provide parity with other GitHub Packages badge types and support the growing ecosystem of Ruby projects using GitHub's package registry.

[jNullj]

Seems like we can also use the graphql API, may be called from repository, owner or org.
This might help us avoid issues, and reduce overall response size.

{
  repository(owner: "OWNER", name: "REPOSITORY") {
    packages(first: 10, names: "EXAMPLE_NAME", packageType:"EXAMPLE_TYPE") {
      edges {
        node {
          name
          versions(first: 10) {
            edges {
              node {
                version
                id
              }
            }
          }
        }
      }
    }
  }
}

We could generalize this into https://img.shields.io/github/package/v/.... that specify package type as a get param, or even uses the API to get the type from the repo and only uses the pacakge name to detect it, but it might be less intuitive to find.
Another approach is to make a generic base class for package version and make a service for each package type using that base class. While being easier to look for, this would result in larger code base.

While the first suggestion is more compact, I think the second would help users find the badges and i tend toward it.

[voltechs]

Hey, that's great! I'm always down for meaningful generalization. That's a pretty slick way to handle all package repository types in one go. I'd be happy with something like this, personally.

[jNullj]

Let's see if anyone picks this one up.
If anyone wants to have a try at this I encourage you to mention it here regardless if a PR is open so we make sure only one person is assigned to the task and track it.

[voltechs]

I may have been mistaken, actually. It appears that Github maybe doesn't allow public access to this endpoint. https://docs.github.com/en/rest/packages/packages?apiVersion=2022-11-28#list-packages-for-an-organization

That being said, I believe that if the package/package repository is public, then Shield.io could use it's own API token to retrieve the data on the end-user's behalf. Obviously we/they'd want to do some reasonable caching to avoid excessive api calls and potential throttling from Github.

[chris48s]

This is a duplicate of #4183 and is blocked on #4169

Here's a quick summary:
We have plenty of GitHub tokens (see info on how this works https://shields.io/blog/token-pool ). They only have read-only access to public data. Making GitHub API requests about packages requires the additional read:packages permission, and none of the tokens we hold have it. Also there is no way to request additional permissions from existing OAuth users.

In order to support GitHub badges which need additional permissions/scopes, we need to (at a very high level):

• Modify the GitHub token pooling code to introduce the concept that different badges need different permissions and different tokens have different permissions. At the moment we assume any token can be used to make any API request.
• Modify the token data structures (DB and in-memory) to store permissions against tokens
• Modify the OAuth app to request additional tokens from future users

..and then a bunch of comms and glue code around that.

Introducing that concept to the token pool code would unblock adding badges that need additional permissions (like this one, but also others) but its gnarly work that nobody has taken forward to date.