Display Your Sponsors in Your GitHub READMEs
A simple nice way to reward your sponsors could be to showcase them in the projects you create on GitHub. And what a better place to do that than in your READMEs? This article will show you how to do that easily!
There are several ways to display your sponsors in your GitHub READMEs, but this article will focus on a single one by using SponsorKit created by Anthony Fu.
sponsorkit 💖 Toolkit for generating sponsors images 😄
SponsorKit is a toolkit for generating sponsors images that supports GitHub Sponsors, Open Collective, Patreon, and Afdian.
Here’s how Anthony uses it himself in antfu/unplugin-auto-import README.
Let’s do our own sponsors image showcasing our GitHub sponsors!
Prerequisites
Before starting, you will need to have a GitHub account and have at least one sponsor.
Then, you will need to create a new GitHub personal access token (classic) with the read:org, and read:user scopes that you can name whatever you want, and keep its value somewhere for the next steps of this tutorial.
You can find more information about how to create a GitHub token in the GitHub documentation.
Create Your Repository
In order to facilitate the process, we have created for you a template repository that you can use to create your own repository: https://github.com/Open-reSource/sponsorkit-starter.
sponsorkit-starter Starter template for SponsorKit
From the Starter Template
You can click on the “Use this template” button to create your own repository.
Then, you will need to fill the form with the name of your repository, a description, and choose if you want to make it public or private. Click on the “Create repository from template” button to create your repository.
It will launch a GitHub Action that will fail, but don’t worry, we will fix that in the next steps.
From a New Repository
It is also possible to create your repository from scratch, clone it locally, and then running the following command:
npx degit Open-reSource/sponsorkit-starterConfigure Your Repository
Your new repository is now created, and should contain the following files:
.github/workflows/scheduler.ymlthat runs the SponsorKit action on a schedule every day, for each merge on the main branch, or manually..env.exampleas described in SponsorKit usage.build.shscript to generate the sponsors images.package.jsonrelying on the latest version of SponsorKit and containing the build script.sponsor.config.tsthat contains the configuration for the generation of the sponsors images.
Change Default Permissions of GITHUB_TOKEN
First important thing to do is to change the default permissions of the GITHUB_TOKEN that is used by the GitHub Action to commit and push the generated sponsors images.
It can be changed by going to your repository settings, then to the “Actions” section, and choose “Read an write permissions” for the “Workflow permissions” option.
You can find more information about this configuration in the GitHub documentation.
Set up the environment variable
By looking at .github/worfklows/scheduler.yml, we can see that it relies on a ${{ secrets.SPONSORS_TOKEN }} environment variable.
We will need to set it up in the GitHub repository settings with “SPONSORS_TOKEN” as a name, and with the value of the GitHub personal access token that we have created in the prerequisites.
You can find more information about how to create a new repository secret in the GitHub documentation.
Configure the GitHub Action
Either after having cloned your repository locally, or directly on GitHub, you will need to edit the .github/worfklows/scheduler.yml to indicate your GitHub username as a value for “SPONSORKIT_GITHUB_LOGIN”.
Commit and push your changes.
Check Your Generated Images
This latter change will trigger the GitHub Action that will generate your sponsors images, commit, and push them at the root level of your repository with the message ” chore: update sponsors.svg”.
For example, you can see the generated sponsors images of the julien-deramond/static repository created from this same template.
(Optional) Generate The Images Locally
More information
It might be useful to know, even if rarely useful, it is also possible to run it locally.
You will need to install the dependencies by running npm i in your terminal.
Then, copy .env.example to .env still at the root level of your repository with the following content:
; GitHub provider.; Token requires the `read:user` and `read:org` scopes.SPONSORKIT_GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxSPONSORKIT_GITHUB_LOGIN=usernameSPONSORKIT_GITHUB_TOKENis the GitHub token you created earlier.SPONSORKIT_GITHUB_LOGINis your GitHub username.
The final step is to run npm run build in your terminal to generate the static files:
ju ߷ ~/j/static ➤ (main) npm run build (0.060674 hrs) 17:48:16SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:16✔ Wrote to ./sponsors.json 17:48:16ℹ Composing SVG... 17:48:16✔ Wrote to ./sponsors.svg 17:48:16✔ Wrote to ./sponsors.png 17:48:16 17:48:17SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:17✔ Wrote to ./sponsors.wide.json 17:48:17ℹ Composing SVG... 17:48:17✔ Wrote to ./sponsors.wide.svg 17:48:17✔ Wrote to ./sponsors.wide.png 17:48:17 17:48:17SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:17✔ Wrote to ./sponsors.part1.json 17:48:17ℹ Composing SVG... 17:48:17✔ Wrote to ./sponsors.part1.svg 17:48:17✔ Wrote to ./sponsors.part1.png 17:48:18 17:48:18SponsorKit v0.8.3
✔ Loaded from cache ./.cache.json 17:48:18✔ Wrote to ./sponsors.part2.json 17:48:18ℹ Composing SVG... 17:48:18✔ Wrote to ./sponsors.part2.svg 17:48:18✔ Wrote to ./sponsors.part2.pngAll the images are now generated at the root level of your repository. You can check them out in your file explorer.
Warning: Once it’s done, please don’t forget to remove at some point your GitHub token from the .env file for security reasons. You won’t probably never re-run it from your local machine.
Use the Generated Images in Your READMEs
Now that the GitHub Action has run, you can use the generated images in your READMEs.
For example, you can use the sponsors.svg image in your README.md file by adding (replace username by your GitHub username):
<p align="center"> <a href="https://cdn.jsdelivr.net/gh/username/static/sponsors.svg"> <img src='https://cdn.jsdelivr.net/gh/username/static/sponsors.svg'/> </a></p>Warning: GitHub can take a while to render the image in your README. If you don’t see it, wait and refresh the page. On my side, it took around 10 minutes to be displayed. As long as the https://cdn.jsdelivr.net/gh/username/static/sponsors.svg URL is showing the image, don’t worry, it will be displayed in your README soon.
Final Result
We don’t have (yet) any sponsors specifically for Open {re}Source, so you can check my own personal sponsors list generated by following this article:
And find it integrated in one of my projects: https://github.com/julien-deramond/update-issue-body#sponsors.