Add your GitHub Sponsors to your project README with Actions

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.

Create a new Personal Access Token. The access token essentially acts like a password for your account, so under no circumstances should you post this anywhere it can be accessed outside of the action.
Provide it with the read:user and read:org scopes so it can access your sponsors.
Add the token as a repository secret, this is done by going to your repository settings and locating the secrets menu. Take note of the secret name, we'll be using it in the next steps.

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: '<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.

Engineering Design Systems In 2022

Fostering Positive Change with Innovation Week

Overview

Preparing the repository

Adding the action

Customizing the Template

Separating by Sponsorship Tier

Conclusion

Related Reading