Add `github-release` package type #418

bdehamer · 2025-03-12T23:34:37Z

Introduces a new github-release package type for identifying specific GitHub Releases.

There is some overlap here with the existing github package type -- in theory you can point to a GitHub release today with a github package type be identifying the release's tag:

pkg:github/foo/[email protected]

However, there may come a time when GitHub releases are decoupled from git tags and it would be helpful to have a way to disambiguate between a plain ol' GitHub repository tag and a named GitHub Release:

pkg:github-release/foo/[email protected]

The most immediate use case for this is in the context of in-toto release predicates where we need to be able to identify a specific GitHub release using a purl.

jkowalleck · 2025-03-18T09:46:44Z

like the idea.

lets think about how a specific file from a release could be pointed out.

lets use this as an example: https://github.com/package-url/packageurl-python/releases/tag/v0.16.0

how would i express that i need the asset https://github.com/package-url/packageurl-python/releases/download/v0.16.0/packageurl_python-0.16.0.tar.gz?
answer is probably: well-known qualifier "file_name"
how would i express that i need a certain file/asset?
answer is probably: subpath

couldyou add those to the spec?

bdehamer · 2025-03-18T13:55:20Z

@jkowalleck

lets think about how a specific file from a release could be pointed out.

This is a good call out! I've added a file_name qualifier to the spec which would allow for the identification of a specific asset within the release. A GitHub "release" provides a flat namespace for uniquely named assets so I don't think we need to use subpath -- file_name alone should be sufficient to uniquely identify a particular asset published as part of a release.

pkg:github-release/foo/[email protected]?file_name=bin-linux.tgz

prabhu · 2025-03-19T10:20:52Z

I like this type. Maybe we expand this a bit and document the various qualifiers including mandatory ones as well.

Required properties as per github

"required": [
      "assets_url",
      "upload_url",
      "tarball_url",
      "zipball_url",
      "created_at",
      "published_at",
      "draft",
      "id",
      "node_id",
      "author",
      "html_url",
      "name",
      "prerelease",
      "tag_name",
      "target_commitish",
      "assets",
      "url"
    ]

Full release schema

{
"title": "Release",
    "description": "A release.",
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "format": "uri"
      },
      "html_url": {
        "type": "string",
        "format": "uri"
      },
      "assets_url": {
        "type": "string",
        "format": "uri"
      },
      "upload_url": {
        "type": "string"
      },
      "tarball_url": {
        "type": [
          "string",
          "null"
        ],
        "format": "uri"
      },
      "zipball_url": {
        "type": [
          "string",
          "null"
        ],
        "format": "uri"
      },
      "id": {
        "type": "integer"
      },
      "node_id": {
        "type": "string"
      },
      "tag_name": {
        "description": "The name of the tag.",
        "type": "string",
        "examples": [
          "v1.0.0"
        ]
      },
      "target_commitish": {
        "description": "Specifies the commitish value that determines where the Git tag is created from.",
        "type": "string",
        "examples": [
          "master"
        ]
      },
      "name": {
        "type": [
          "string",
          "null"
        ]
      },
      "body": {
        "type": [
          "string",
          "null"
        ]
      },
      "draft": {
        "description": "true to create a draft (unpublished) release, false to create a published one.",
        "type": "boolean",
        "examples": [
          false
        ]
      },
      "prerelease": {
        "description": "Whether to identify the release as a prerelease or a full release.",
        "type": "boolean",
        "examples": [
          false
        ]
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "published_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "author": {
        "title": "Simple User",
        "description": "A GitHub user.",
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "login": {
            "type": "string",
            "examples": [
              "octocat"
            ]
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "examples": [
              1
            ]
          },
          "node_id": {
            "type": "string",
            "examples": [
              "MDQ6VXNlcjE="
            ]
          },
          "avatar_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://github.com/images/error/octocat_happy.gif"
            ]
          },
          "gravatar_id": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "41d064eb2195891e12d0413f63227ea7"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://api.github.com/users/octocat"
            ]
          },
          "html_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://github.com/octocat"
            ]
          },
          "followers_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://api.github.com/users/octocat/followers"
            ]
          },
          "following_url": {
            "type": "string",
            "examples": [
              "https://api.github.com/users/octocat/following{/other_user}"
            ]
          },
          "gists_url": {
            "type": "string",
            "examples": [
              "https://api.github.com/users/octocat/gists{/gist_id}"
            ]
          },
          "starred_url": {
            "type": "string",
            "examples": [
              "https://api.github.com/users/octocat/starred{/owner}{/repo}"
            ]
          },
          "subscriptions_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://api.github.com/users/octocat/subscriptions"
            ]
          },
          "organizations_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://api.github.com/users/octocat/orgs"
            ]
          },
          "repos_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://api.github.com/users/octocat/repos"
            ]
          },
          "events_url": {
            "type": "string",
            "examples": [
              "https://api.github.com/users/octocat/events{/privacy}"
            ]
          },
          "received_events_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://api.github.com/users/octocat/received_events"
            ]
          },
          "type": {
            "type": "string",
            "examples": [
              "User"
            ]
          },
          "site_admin": {
            "type": "boolean"
          },
          "starred_at": {
            "type": "string",
            "examples": [
              "\"2020-07-09T00:17:55Z\""
            ]
          },
          "user_view_type": {
            "type": "string",
            "examples": [
              "public"
            ]
          }
        },
        "required": [
          "avatar_url",
          "events_url",
          "followers_url",
          "following_url",
          "gists_url",
          "gravatar_id",
          "html_url",
          "id",
          "node_id",
          "login",
          "organizations_url",
          "received_events_url",
          "repos_url",
          "site_admin",
          "starred_url",
          "subscriptions_url",
          "type",
          "url"
        ]
      },
      "assets": {
        "type": "array",
        "items": {
          "title": "Release Asset",
          "description": "Data related to a release.",
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            },
            "browser_download_url": {
              "type": "string",
              "format": "uri"
            },
            "id": {
              "type": "integer"
            },
            "node_id": {
              "type": "string"
            },
            "name": {
              "description": "The file name of the asset.",
              "type": "string",
              "examples": [
                "Team Environment"
              ]
            },
            "label": {
              "type": [
                "string",
                "null"
              ]
            },
            "state": {
              "description": "State of the release asset.",
              "type": "string",
              "enum": [
                "uploaded",
                "open"
              ]
            },
            "content_type": {
              "type": "string"
            },
            "size": {
              "type": "integer"
            },
            "download_count": {
              "type": "integer"
            },
            "created_at": {
              "type": "string",
              "format": "date-time"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            },
            "uploader": {
              "anyOf": [
                {
                  "type": "null"
                },
                {
                  "title": "Simple User",
                  "description": "A GitHub user.",
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "email": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "login": {
                      "type": "string",
                      "examples": [
                        "octocat"
                      ]
                    },
                    "id": {
                      "type": "integer",
                      "format": "int64",
                      "examples": [
                        1
                      ]
                    },
                    "node_id": {
                      "type": "string",
                      "examples": [
                        "MDQ6VXNlcjE="
                      ]
                    },
                    "avatar_url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://github.com/images/error/octocat_happy.gif"
                      ]
                    },
                    "gravatar_id": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "examples": [
                        "41d064eb2195891e12d0413f63227ea7"
                      ]
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://api.github.com/users/octocat"
                      ]
                    },
                    "html_url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://github.com/octocat"
                      ]
                    },
                    "followers_url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://api.github.com/users/octocat/followers"
                      ]
                    },
                    "following_url": {
                      "type": "string",
                      "examples": [
                        "https://api.github.com/users/octocat/following{/other_user}"
                      ]
                    },
                    "gists_url": {
                      "type": "string",
                      "examples": [
                        "https://api.github.com/users/octocat/gists{/gist_id}"
                      ]
                    },
                    "starred_url": {
                      "type": "string",
                      "examples": [
                        "https://api.github.com/users/octocat/starred{/owner}{/repo}"
                      ]
                    },
                    "subscriptions_url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://api.github.com/users/octocat/subscriptions"
                      ]
                    },
                    "organizations_url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://api.github.com/users/octocat/orgs"
                      ]
                    },
                    "repos_url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://api.github.com/users/octocat/repos"
                      ]
                    },
                    "events_url": {
                      "type": "string",
                      "examples": [
                        "https://api.github.com/users/octocat/events{/privacy}"
                      ]
                    },
                    "received_events_url": {
                      "type": "string",
                      "format": "uri",
                      "examples": [
                        "https://api.github.com/users/octocat/received_events"
                      ]
                    },
                    "type": {
                      "type": "string",
                      "examples": [
                        "User"
                      ]
                    },
                    "site_admin": {
                      "type": "boolean"
                    },
                    "starred_at": {
                      "type": "string",
                      "examples": [
                        "\"2020-07-09T00:17:55Z\""
                      ]
                    },
                    "user_view_type": {
                      "type": "string",
                      "examples": [
                        "public"
                      ]
                    }
                  },
                  "required": [
                    "avatar_url",
                    "events_url",
                    "followers_url",
                    "following_url",
                    "gists_url",
                    "gravatar_id",
                    "html_url",
                    "id",
                    "node_id",
                    "login",
                    "organizations_url",
                    "received_events_url",
                    "repos_url",
                    "site_admin",
                    "starred_url",
                    "subscriptions_url",
                    "type",
                    "url"
                  ]
                }
              ]
            }
          },
          "required": [
            "id",
            "name",
            "content_type",
            "size",
            "state",
            "url",
            "node_id",
            "download_count",
            "label",
            "uploader",
            "browser_download_url",
            "created_at",
            "updated_at"
          ]
        }
      },
      "body_html": {
        "type": "string"
      },
      "body_text": {
        "type": "string"
      },
      "mentions_count": {
        "type": "integer"
      },
      "discussion_url": {
        "description": "The URL of the release discussion.",
        "type": "string",
        "format": "uri"
      },
      "reactions": {
        "title": "Reaction Rollup",
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "total_count": {
            "type": "integer"
          },
          "+1": {
            "type": "integer"
          },
          "-1": {
            "type": "integer"
          },
          "laugh": {
            "type": "integer"
          },
          "confused": {
            "type": "integer"
          },
          "heart": {
            "type": "integer"
          },
          "hooray": {
            "type": "integer"
          },
          "eyes": {
            "type": "integer"
          },
          "rocket": {
            "type": "integer"
          }
        },
        "required": [
          "url",
          "total_count",
          "+1",
          "-1",
          "laugh",
          "confused",
          "heart",
          "hooray",
          "eyes",
          "rocket"
        ]
      }
    },
    "required": [
      "assets_url",
      "upload_url",
      "tarball_url",
      "zipball_url",
      "created_at",
      "published_at",
      "draft",
      "id",
      "node_id",
      "author",
      "html_url",
      "name",
      "prerelease",
      "tag_name",
      "target_commitish",
      "assets",
      "url"
    ]
  }

bdehamer · 2025-04-03T17:08:10Z

@prabhu I don't think its necessary capture all of the release's properties in the PURL. As long as there is enough information to uniquely identify a specific GitHub release we should be good.

jaimergp · 2025-04-03T21:30:26Z

Github Releases are mutable though. I can remove and reupload a new artifact with the same name. I think requiring the SHA256 or upload timestamp would be beneficial.

bdehamer · 2025-04-03T21:59:09Z

@jaimergp it turns out that the feature I'm working (the one which inspired the need for this new purl type) is to make releases immutable. When used in that context, the repo and tag should be sufficient to uniquely identify the release. Perhaps an optional checksum qualifier could be added to account for the current state of mutable releases?

Signed-off-by: Brian DeHamer <[email protected]>

bdehamer · 2025-04-03T23:54:12Z

@jaimergp I documented the checksum qualifier and also added a test in test-suite-data.json

> When percent-encoding is required, all characters MUST be encoded except for the colon ':'.

fix examples for `github-release` examples > When percent-encoding is required, all characters MUST be encoded except for the colon ':'.

pombredanne · 2025-04-04T13:10:18Z

Hey, I posted some comment in #299 (comment) ... I need to think more about that one and how we can discover a release.

pombredanne · 2025-07-02T06:20:05Z

PURL-TYPES.rst

+
+      pkg:github-release/cli/[email protected]
+      pkg:github-release/foo/[email protected]?repository_url=https:%2F%2Ffoobar.ghe.com
+      pkg:github-release/foo/[email protected]?file_name=bin-linux.tgz&checksum=sha256:deadbeef


Is there anything that could not be accomplished with the github type and a file_name qualifier?

Concrete example of why this is different from the github type: pkg:github-release/keepassxc/[email protected]?file_name=KeePassXC-2.7.10-arm64.dmg from https://github.com/keepassxreboot/keepassxc/releases/tag/2.7.10. The file is not part of the Git repository so it cannot be referenced using pkg:github. You'd need to represent it with a pkg:generic. I'm not sure what pkg:github-release gives beyond pkg:generic. GitHub Releases is a place where you could be downloading a package from but isn't a package management system. There's no implied meaning about version numbers or the content or format of the file or dependencies between releases.

So now that a released file is immutable, why would this not be fine to point to an exact file in a release? And a release is always attached to a git tag so what about this?

pkg:github/keepassxreboot/[email protected]?file_name=KeePassXC-2.7.10-arm64.dmg that would resolve to this https://github.com/keepassxreboot/keepassxc/releases/download/2.7.10/KeePassXC-2.7.10-arm64.dmg ?

And https://github.com/keepassxreboot/keepassxc/releases/download/2.7.10/KeePassXC-2.7.10-Win64.msi to pkg:github/keepassxreboot/[email protected]?file_name=KeePassXC-2.7.10-Win64.msi

(Note that works even if releases would be mutable, these are two different things)

It seems weird to me for pkg:github/keepassxreboot/[email protected] to refer to a tag in a Git repository and pkg:github/keepassxreboot/[email protected]?file_name=KeePassXC-2.7.10-arm64.dmg to refer to an arbitrary file that exists alongside that Git repository. I guess it's kind of similar to pkg:pypi where the package is made of multiple files that are not necessarily related, except that for pkg:github the file_name qualifier would change the mechanism for retrieving the package.

pombredanne · 2025-07-26T20:17:49Z

... and also in all cases, after the merge of PR #514, PURL types are now defined in JSON: 😇 😁

See Refine Purl type schema #514

With the new approach... this PR would need to be updated.

jkowalleck linked an issue Mar 18, 2025 that may be closed by this pull request

Proposal: github-release type #299

Open

jkowalleck added Proposed new type type: github-release Proposed new type labels Mar 18, 2025

jkowalleck previously approved these changes Mar 18, 2025

View reviewed changes

bdehamer dismissed jkowalleck’s stale review via e3aa0d6 March 18, 2025 13:50

jkowalleck previously approved these changes Mar 18, 2025

View reviewed changes

bdehamer dismissed jkowalleck’s stale review via 2804d56 April 3, 2025 23:49

bdehamer added 2 commits April 3, 2025 16:50

add github-release purl type

e08430b

Signed-off-by: Brian DeHamer <[email protected]>

add file_name qualifier for github-release

928160d

Signed-off-by: Brian DeHamer <[email protected]>

bdehamer force-pushed the bdehamer/github-release branch from 2804d56 to 56783d3 Compare April 3, 2025 23:52

bdehamer added 2 commits April 3, 2025 16:52

add checksum qualifier to github-release type

82cd85f

Signed-off-by: Brian DeHamer <[email protected]>

add test case for github-release type

4975be7

Signed-off-by: Brian DeHamer <[email protected]>

bdehamer force-pushed the bdehamer/github-release branch from 56783d3 to 4975be7 Compare April 3, 2025 23:52

jkowalleck added 3 commits April 4, 2025 08:19

fixed checksum qualifier example for github-release

63eaca9

fix encoding for github-releases tests

f29f9d7

> When percent-encoding is required, all characters MUST be encoded except for the colon ':'.

Update PURL-TYPES.rst

60e42be

fix examples for `github-release` examples > When percent-encoding is required, all characters MUST be encoded except for the colon ':'.

jkowalleck approved these changes Apr 4, 2025

View reviewed changes

jkowalleck requested a review from a team April 4, 2025 06:29

pombredanne mentioned this pull request Apr 4, 2025

Proposal: github-release type #299

Open

johnmhoran added this to the 1.1 milestone Apr 4, 2025

pombredanne reviewed Jul 2, 2025

View reviewed changes

mjherzog removed this from the PURL-TBD milestone Sep 18, 2025

Add github-release package type #418

Are you sure you want to change the base?

Add github-release package type #418

Uh oh!

Conversation

bdehamer commented Mar 12, 2025

Uh oh!

jkowalleck commented Mar 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bdehamer commented Mar 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

prabhu commented Mar 19, 2025

Uh oh!

bdehamer commented Apr 3, 2025

Uh oh!

jaimergp commented Apr 3, 2025

Uh oh!

bdehamer commented Apr 3, 2025

Uh oh!

bdehamer commented Apr 3, 2025

Uh oh!

pombredanne commented Apr 4, 2025

Uh oh!

pombredanne Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

matt-phylum Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

pombredanne Jul 26, 2025

Choose a reason for hiding this comment

Uh oh!

matt-phylum Jul 28, 2025

Choose a reason for hiding this comment

Uh oh!

pombredanne commented Jul 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Add `github-release` package type #418

Add `github-release` package type #418

jkowalleck commented Mar 18, 2025 •

edited

Loading

bdehamer commented Mar 18, 2025 •

edited

Loading