https://github.com/devlooped/sponsorlink
SponsorLink: an attempt at OSS sustainability
https://github.com/devlooped/sponsorlink
oss sponsors sponsorships sustainability
Last synced: 3 months ago
JSON representation
SponsorLink: an attempt at OSS sustainability
- Host: GitHub
- URL: https://github.com/devlooped/sponsorlink
- Owner: devlooped
- License: mit
- Created: 2023-01-22T23:47:49.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-09T20:12:07.000Z (4 months ago)
- Last Synced: 2026-03-10T01:42:56.215Z (4 months ago)
- Topics: oss, sponsors, sponsorships, sustainability
- Language: C#
- Homepage: https://www.devlooped.com/SponsorLink
- Size: 3.04 MB
- Stars: 42
- Watchers: 0
- Forks: 4
- Open Issues: 10
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- License: license.txt
Awesome Lists containing this project
README
#  SponsorLink
Core specification and reference implementation for integrating GitHub Sponsors into
libraries and tools.
[](https://www.devlooped.com/SponsorLink/spec/)
[](https://www.nuget.org/packages/dotnet-sponsor)
[](https://www.nuget.org/packages/dotnet-sponsor)
Integrate [GitHub Sponsors](https://github.com/sponsors) into your libraries so that
users can be properly linked to their sponsorship to unlock features or simply get
the recognition they deserve for supporting your project.
SponsorLink supports two scenarios:
1. Open source project developers or maintainers who are looking to incentivize
sponsors to contribute to the project, to ensure ongoing and recurring income
that can help ensure proper maintenance and further feature work.
2. Open source project consumers, who want to ensure their dependencies have
an active team that can provide support, bug fixes and add new features.
[Explore the documentation site](https://www.devlooped.com/SponsorLink).
## Why GitHub sponsors?
[GitHub Sponsors](https://github.com/sponsors/) is a great way to support open
source projects, and it's available throughout most of the world.
That is not to say that there aren't other mechanisms that can provide similar
functionality and support. At this point, however, the tooling, API access and
very 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's
sponsorship and the libraries they use, in an easy to check, secure and offline
way.
## How it works
Roughly, the reference implementation works as follows:
1. A library/tool author adds a check (i.e. on usage, build, etc.) for a
[sponsor manifest](https://www.devlooped.com/SponsorLink/spec/#sponsor-manifest)
at 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 stating
that 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 suggested [dotnet sponsor global tool](https://www.nuget.org/packages/dotnet-sponsor) and runs `sponsor sync [account]` to sync their sponsorships.
* On first run, user accepts usage terms and conditions.
4. The tool fetches the author's [sponsorable manifest](https://www.devlooped.com/SponsorLink/spec/#sponsorable-manifest) from their community files repo
at `https://github.com/[account]/.github/blob/[default_branch]/sponsorlink.jwt` and
uses its information to authenticate the user on github.com with an OAuth app belonging
to 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 location
mentioned in step 1. This manifest is signed, has an expiration date and can be
verified by the library/tool without any network access.
Notes:
* Sponsor manifest expires monthly (like GitHub sponsorships themselves) and is signed
with a private key only the author has access to. Its corresponding public key is
public and accessible on the sponsorable manifest.
* Users can optionally turn on/off auto-sync, so that after the first sync, the author can
automatically refresh the manifest on the user's behalf by re-running the sync command
unattended.
* 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 at [OSS Authors](https://www.devlooped.com/SponsorLink/github/oss/)
* Typically, an autor would consider any of the above roles to qualify as an active
sponsor (direct, indirect and implicit, respectively), but the actual behavior is up to the library/tool author.
[Explore the documentation site](https://www.devlooped.com/SponsorLink) to learn more,
and make sure to check the [privacy statement](https://www.devlooped.com/SponsorLink/privacy/).
## Integrating via NuGet for .NET
The reference implementation .NET global tool, `dotnet-sponsor`, provides generic
manifest discovery and sync capabilities, but the actual check from within a library
or tool is left to the author.
> [!NOTE]
> For now, the tool works only with GitHub sponsors as a funding platform.
Since the sponsor manifest is a standard JWT token, it can be verified by any JWT
library in any language and at any point in the library/tool usage (at installation
time, run-time, build-time, etc.).
If you are looking for inspiration on how to do this for .NET with NuGet and C#,
check the [the analyzer sample](samples/dotnet).
## Release Announcements on X
When a GitHub release is published, SponsorLink can automatically post a threaded
announcement to X (formerly Twitter). The release body is summarized by the
[Grok](https://x.ai) AI model into a ranked list of emoji-prefixed highlights,
formatted into a reply chain of up to 280-character posts.
### Announcement Conditions
An announcement is posted when **all** of the following are true:
- The release is not a draft.
- The release body is not empty.
- The release body contains at least one recognized section title (see below),
**or** the [force-announce marker](#html-comment-markers) is present.
- The release body does not contain the [skip-announce marker](#html-comment-markers).
- All required [configuration settings](#configuration) are present.
Deduplication is enforced via Azure Table Storage: a release that has already been
announced is skipped even if the webhook fires again.
#### Release Section Titles
The announcement is gated on the presence of at least one of the category headings
defined in [`.github/release.yml`](.github/release.yml), which is synchronized from
[devlooped/oss](https://github.com/devlooped/oss/blob/main/.github/release.yml).
### HTML Comment Markers
Two special HTML comment markers can be placed anywhere in the release body:
| Marker | Effect |
|---|---|
| `` | **Skip** � suppresses the announcement for this release, even if it would otherwise qualify. |
| `` | **Force** � publishes the announcement regardless of whether the release was just published or was edited after the fact. Useful for announcing an edited release that was initially skipped. |
Markers are case-insensitive (`` and `` are equivalent) and
tolerate surrounding whitespace inside the comment.
### Configuration
All settings are read from application configuration (environment variables,
Azure Key Vault, or `appsettings.json`).
#### X / Twitter (OAuth 1.0a)
| Setting | Description |
|---|---|
| `X:ConsumerKey` | OAuth consumer key (API key) for the X app. |
| `X:ConsumerSecret` | OAuth consumer secret for the X app. |
| `X:AccessToken` | Access token for the X account that will post. |
| `X:AccessTokenSecret` | Access token secret for the X account that will post. |
#### AI Summarization (Grok)
| Setting | Description | Default |
|---|---|---|
| `AI:Clients:Grok:Endpoint` | xAI API base URL. | `https://api.x.ai/v1` |
| `AI:Clients:Grok:ModelId` | Model to use for summarization. | `grok-4-1-fast-non-reasoning` |
| `AI:Clients:Grok:ApiKey` | xAI API key (secret). | � |
When `AI:Clients:Grok:ApiKey` is absent the summarizer is disabled and no
announcements are posted.