Repository files navigation

Core specification and reference implementation for integrating GitHub Sponsors intolibraries and tools.

IntegrateGitHub Sponsors into your libraries so thatusers can be properly linked to their sponsorship to unlock features or simply getthe recognition they deserve for supporting your project.

SponsorLink supports two scenarios:

1. Open source project developers or maintainers who are looking to incentivizesponsors to contribute to the project, to ensure ongoing and recurring incomethat can help ensure proper maintenance and further feature work.

2. Open source project consumers, who want to ensure their dependencies havean active team that can provide support, bug fixes and add new features.

Explore the documentation site.

GitHub Sponsors is a great way to support opensource projects, and it's available throughout most of the world.

That is not to say that there aren't other mechanisms that can provide similarfunctionality and support. At this point, however, the tooling, API access andvery low barrier to entry make it a great initial choice for SponsorLink.

That said, the reference implementation is not deeply tied to GitHub Sponsors,and the specification is entirely agnostic to the sponsorship platform.

The value SponsorLink brings is in providing the "missing" link between a user'ssponsorship and the libraries they use, in an easy to check, secure and offlineway.

Roughly, the reference implementation works as follows:

1. A library/tool author adds a check (i.e. on usage, build, etc.) for asponsor manifestat a well-known location in the local machine (i.e.~/.sponsorlink/github/devlooped.jwt.). If not found, the library/tool issues a notice to the user, typically statingthat they are seeking funding, how to fund the project and how to sync their status,which is unknown at this point.
2. User decides to sponsor the project, does so on github.com
3. User installs the suggesteddotnet sponsor global tool and runssponsor sync [account] to sync their sponsorships.
   • On first run, user accepts usage terms and conditions.
4. The tool fetches the author'ssponsorable manifest from their community files repoathttps://github.com/[account]/.github/blob/[default_branch]/sponsorlink.jwt anduses its information to authenticate the user on github.com with an OAuth app belongingto the author, using device flow.
5. The resulting authentication token is used to invoke the author's backend ("issuer")API to retrieve the user's sponsor manifest (if any) and persist it at the well-known locationmentioned in step 1. This manifest is signed, has an expiration date and can beverified by the library/tool without any network access.

Notes:

• Sponsor manifest expires monthly (like GitHub sponsorships themselves) and is signedwith a private key only the author has access to. Its corresponding public key ispublic and accessible on the sponsorable manifest.
• Users can optionally turn on/off auto-sync, so that after the first sync, the author canautomatically refresh the manifest on the user's behalf by re-running the sync commandunattended.
• Users can have the following role claims:
  • user: the user is direct sponsor of the author.
  • org: the user is a member of an organization that sponsors the author.
  • contrib: the user is a contributor to the author's project(s).
  • team: the user is team a member of the author's organization.
  • oss: the user is an author or contributor to an active open-source nuget package.Elegibility can be checked atOSS Authors
• Typically, an autor would consider any of the above roles to qualify as an activesponsor (direct, indirect and implicit, respectively), but the actual behavior is up to the library/tool author.

Explore the documentation site to learn more,and make sure to check theprivacy statement.

Active SponsorLink sync usage by sponsorship kind:

The reference implementation .NET global tool,dotnet-sponsor, provides genericmanifest discovery and sync capabilities, but the actual check from within a libraryor tool is left to the author.

Since the sponsor manifest is a standard JWT token, it can be verified by any JWTlibrary in any language and at any point in the library/tool usage (at installationtime, run-time, build-time, etc.).

If you are looking for inspiration on how to do this for .NET with NuGet and C#,check thethe analyzer sample.