Add your GitHub Sponsors to your project README with Actions

A simple way to add some value to your GitHub Sponsorship tiers with the help of GitHub Actions.

Published 7 months ago
6 min read
1,432 views

Overview

Some time ago I wrote a GitHub action that would allow you to add your GitHub Sponsors to your project README. I've been using it for a while now and wanted to share how you can also use it to add value to your sponsorship tiers. If you want to skip this and just go straight to the documentation click here.

Wall of default GitHub avatars
Avatar walls for all

Preparing the repository

In order for the action to make changes to your repository on your behalf you need to provide it with a couple of things.

With the above done, your repository should have the required access to pull your sponsorship data from the GitHub API and write the changes to your project.

Adding the action

To create a new action workflow you need to create a file within the .github/workflows directory within the root of your repository, if it doesn't already exist, create it. Within it create a file called sponsors.yml, where the action will live. After that add the following.

.github/workflows/sponsors.yml
name: Generate Sponsors README
on:
  workflow_dispatch:
  schedule:
    # This is a cron schedule, it will run every day at 15:30. You can change this to whatever you want.x
    - cron: 30 15 * * 0-6
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # Checkout the repository
      - name: Checkout ๐Ÿ›Ž๏ธ
        uses: actions/checkout@v2

      # Generate the sponsors
      - name: Generate Sponsors ๐Ÿ’–
        uses: JamesIves/github-sponsors-readme-action@v1
        with:
          # The name of this should correspond with the name you gave your secret, in my example this is 'PAT'.
          token: ${{ secrets.PAT }}

          # This should point to your project's readme, or any other type of markdown file you want to add sponsorship information to.
          file: 'README.md'

      # Deploy the changes back to the main branch of the repository
      - name: Deploy to GitHub Pages ๐Ÿš€
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          # Typically this should be the name of the base branch, in many cases this is 'main'.
          branch: main

          # As we're deploying changes to our markdown files, this needs to be . to push the root directory back to the repository.
          folder: '.'
Keep an eye out for things in the above example that may be specific to your project. I've added comments to those parts to better help you navigate them!

The last thing to do is to edit your README file to add the required markers. The action will look for these markers and replace them with the appropriate sponsorship information using the default template. You can change the template by adding a template parameter to the action, but we'll get to that later.

README.md
# lab ๐Ÿงช

Random experiments and projects.

## Sponsors โค๏ธ

Check out our awesome sponsors!

<!-- sponsors -->
<!-- sponsors -->

Trigger the workflow from the repositories workflow tab and once it finishes running you should see the content populated in the README if you have any sponsors!

Example of the action running.
This is the default template, keep reading to learn how to change it!

Customizing the Template

If you want to customize the template you can do so using the template input in your sponsors.yml file. The template input can be whatever you want. You can make it HTML or Markdown, it's up to you, it will be repeated for each sponsor that you have. There are a number of variables available that the action will replace with the appropriate data that you can use to customize the output. There are variables for the user's full name, username, profile URL and website URL (if provided), for a full list of available variables click here.

For example, the following workflow will render sponsors in a markdown list.

.github/workflows/sponsors.yml
- name: Generate Sponsors ๐Ÿ’–
  uses: JamesIves/github-sponsors-readme-action@v1
  with:
    token: ${{ secrets.PAT }}
    file: 'README.md'
    template: '* [{{{ name }}}]({{{ url }}}) - {{{ login }}}'

Or you could get creative and use some GitHub-supported HTML too!

.github/workflows/sponsors.yml
- name: Generate Sponsors ๐Ÿ’–
  uses: JamesIves/github-sponsors-readme-action@v1
  with:
    token: ${{ secrets.PAT }}
    file: 'README.md'
    template: template: '<a href="https://github.com/{{{ login }}}"><img src="https://github.com/{{{ login }}}.png" width="80px" alt="{{{ login }}}" /></a>&nbsp;&nbsp;'

Separating by Sponsorship Tier

If you have multiple sponsorship tiers you can separate them by using the minimum and maximum inputs which translates to the US dollar amount in cents. The action will only render sponsors that fall within the range. For example, if you have a bronze tier that's $1 - $4, a silver tier that's $5 - $9 and a gold tier that's $10+ you can separate them by running the action multiple times within the same workflow. You can even combine this with the template input to customize the output for each tier.

.github/workflows/sponsors.yml
name: Generate Sponsors README
on:
  workflow_dispatch:
  schedule:
    - cron: 30 15 * * 0-6
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout ๐Ÿ›Ž๏ธ
        uses: actions/checkout@v2

      - name: Generate Bronze Sponsors ๐ŸคŽ
        uses: JamesIves/github-sponsors-readme-action@v1
        with:
          token: ${{ secrets.PAT }}
          file: 'README.md'
          maximum: 499
          marker: bronze

      - name: Generate Silver Sponsors ๐Ÿค
        uses: JamesIves/github-sponsors-readme-action@v1
        with:
          token: ${{ secrets.PAT }}
          file: 'README.md'
          minimum: 500
          maximum: 999
          marker: silver

      - name: Generate Gold Sponsors ๐Ÿ’›
        uses: JamesIves/github-sponsors-readme-action@v1
        with:
          token: ${{ secrets.PAT }}
          file: 'README.md'
          minimum: 1000
          marker: gold

      - name: Deploy to GitHub Pages ๐Ÿš€
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: main
          folder: '.'

For each time you run the action you'll need to provide a marker input that corresponds to the marker you've added to your README file. This is so it knows where to place the content.

README.md
# lab ๐Ÿงช

Random experiments and projects.

## Gold Sponsors ๐Ÿ’›

<!-- gold -->
<!-- gold -->

## Silver Sponsors ๐Ÿค

<!-- silver -->
<!-- silver -->

## Bronze Sponsors ๐ŸคŽ

<!-- bronze -->
<!-- bronze -->

You'll end up with something like the following as a result.

Example of the action running with multiple tiers.
You can get crazy with it and add as many sponsorship tiers as you like!

Conclusion

And that's it! You should now have a workflow that will automatically update your README with your sponsors daily. This way you won't accidently leave anyone out if you were previously maintaining this list by hand. If you have any questions or issues feel free to open an issue or discussion post on GitHub.