@jamesives/github-sponsors-readme-action v1.5.3

Getting Started ✈️

You can include the action in your workflow to trigger on any event that GitHub Actions supports.

!IMPORTANT You'll need to provide the action with a Personal Access Token (PAT) scoped to read:user and read:org.

Additionally, this action only applies the template within the workspace. You will need to combine it with a deployment action in order to commit it to your project. You can see a full example of this below.

name: Generate Sponsors README
on:
  workflow_dispatch:
  schedule:
    - cron: 30 15 * * 0-6
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v2

      - name: Generate Sponsors 💖
        uses: JamesIves/github-sponsors-readme-action@v1
        with:
          token: ${{ secrets.PAT }}
          file: 'README.md'

      # ⚠️ Note: You can use any deployment step here to automatically push the README
      # changes back to your branch.
      - name: Deploy to GitHub Pages 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: main
          folder: '.'

You'll also need to the following <!-- sponsors --><!-- sponsors --> in your .md file so the action knows where to place the data.

# Awesome Project

Go you!

## Sponsors

These are our really cool sponsors!

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

!TIP Looking for a more guided walkthrough? Check out the following article for more details on how to set everything up in your project.

Install as a Node Module 📦

If you'd like to use the functionality provided by this action in your own action you can either create a composite action, or you can install it using yarn or npm by running the following commands. It's available on both the npm and GitHub registry.

yarn add @jamesives/github-sponsors-readme-action

npm install @jamesives/github-sponsors-readme-action

It can then be imported into your project like so.

import run from '@jamesives/github-sponsors-readme-action'

run({
  token: process.env.GITHUB_TOKEN
})

Calling the functions directly will require you to pass in an object containing the variables found in the configuration section.

Configuration 📁

The with portion of the workflow must be configured before the action will work. You can add these in the with section found in the examples above. Any secrets must be referenced using the bracket syntax and stored in the GitHub repository's Settings/Secrets menu. You can learn more about setting environment variables with GitHub actions here.

Required Setup

The following options must be configured.

Optional Choices

Deployment Status

The action will export a step output as sponsorship-status that you can use in your workflow to determine if the task was successful or not. You can find an explanation of each status type below.

Modifying the Template 🔧

You can modify the template that gets generated in your file by using the template input. This input allows you to leverage mustache templating to modify what is displayed. The following values are available.

You're able to use markdown or GitHub approved basic HTML. The default template can be found here.

name: Generate Sponsors README
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v2

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

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

# Awesome Project

Go you!

## Sponsors

These are our really cool sponsors!

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

Separating by Sponsorship Tier ✨

If you'd like to highlight certain users who contribute to a specific sponsorship tier you can do so using a combination of the minimum, maximum and marker inputs. The minimum / maximum inputs equal their dollar contribution in cents.

name: Generate Sponsors README
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v2

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

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

# Awesome Project

Go you!

## Gold Sponsors

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

## Silver Sponsors

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