Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jamesives/github-sponsors-readme-action

❤️ This GitHub Action will automatically add your GitHub Sponsors to your README. It can be configured in multiple ways allowing you to display and breakdown your sponsors by price tier with fallbacks.
https://github.com/jamesives/github-sponsors-readme-action

action actions breakdown-sponsors github-actions github-sponsors hacktoberfest hacktoberfest2023 readme sponsor sponsors workflow

Last synced: about 1 month ago
JSON representation

Host: GitHub
URL: https://github.com/jamesives/github-sponsors-readme-action
Owner: JamesIves
License: mit
Created: 2021-04-29T04:38:19.000Z (over 3 years ago)
Default Branch: dev
Last Pushed: 2024-04-30T10:51:52.000Z (7 months ago)
Last Synced: 2024-05-01T14:32:54.376Z (7 months ago)
Topics: action, actions, breakdown-sponsors, github-actions, github-sponsors, hacktoberfest, hacktoberfest2023, readme, sponsor, sponsors, workflow
Language: TypeScript
Homepage: https://github.com/marketplace/actions/add-github-sponsors-to-readme
Size: 14.7 MB
Stars: 61
Watchers: 3
Forks: 18
Open Issues: 12
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md

Awesome Lists containing this project

README

✨ GitHub Sponsors Readme Action ✨

This GitHub Action will automatically add your GitHub Sponsors to your README. It can be configured in multiple ways allowing you to display and breakdown your sponsors by price tier with fallbacks. It also includes templating support so you can display your sponsors how you'd like.

Maintenance of this project is made possible by all the contributors and sponsors. If you'd like to sponsor this project and have your avatar or company logo appear below click here. 💖

## Getting Started ✈️

You can include the action in your workflow to trigger on any event that [GitHub Actions supports](https://help.github.com/en/articles/events-that-trigger-workflows).

> [!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.

```yml
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 `` in your `.md` file so the action knows where to place the data.

```md
# Awesome Project

Go you!

## Sponsors

These are our really cool 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](https://jamesiv.es/blog/github/actions/2023/06/30/add-your-github-sponsors-to-your-project-readme).

#### 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](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action), or you can install it using [yarn](https://yarnpkg.com/) or [npm](https://www.npmjs.com/get-npm) by running the following commands. It's available on both the [npm](https://www.npmjs.com/package/@jamesives/github-sponsors-readme-action) and [GitHub registry](https://github.com/JamesIves/github-sponsors-readme-action/packages/229982).

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

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

It can then be imported into your project like so.

```javascript
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](https://github.com/JamesIves/github-sponsors-readme-action#configuration-).

## 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](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets).

#### Required Setup

The following options must be configured.

| Key | Value Information | Type | Required |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| `token` | You must provide the action with a Personal Access Token (PAT) with the `read:user` and `read:org` permission scope and store it in the `secrets / with` menu **as a secret**. This should be generated from the account or organization that receives sponsorship, and depending on your use case you may need to provide additional scopes. [Learn more about creating and using encrypted secrets here](https://docs.github.com/en/actions/reference/encrypted-secrets). | `with` | **Yes** |
| `file` | This should point to the file that you're generating, for example `README.md` or `path/to/CREDITS.md`. Defaults to `README.md` if no value is provided. | `with` | **Yes** |

#### Optional Choices

| Key | Value Information | Type | Required |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| `organization` | If you're displaying sponsorship information as or for an organization you should toggle this option to `true`. You also need to provide the action with an `read:org` and `read:user` scoped PAT. **Note**: The PAT must belong to an owner of the organization. | `with` | **No** |
| `minimum` | Using this input you can set the minimum sponsorship threshold. For example setting this to `500` will only display sponsors who give of `$5 USD` and more. By default the action will display all of your sponsors. | `with` | **No** |
| `maximum` | Using this input you can set the maximum sponsorship threshold. For example setting this to `500` will only display sponsors who give of `$5 USD` and less. By default the action will display all of your sponsors. | `with` | **No** |
| `marker` | This allows you to modify the marker comment that is placed in your file. By default this is set to sponsors - ` `, if you set this to `gold` for example you can place ` ` in your file. | `with` | **No** |
| `fallback` | Allows you to specify a fallback if you have no sponsors. By default nothing is displayed. | `with` | **No** |
| `template` | Allows you to modify the default template. Please refer to the `template` section of this README for more information. | `with` | **No** |
| `active-only` | If set to `false`, inactive sponsors will be displayed. This can be useful if you want to display all sponsors, regardless of their status. By default this is set to `true`. | `with` | **No** |
| `include-private` | If set to `true`, private sponsors will be displayed in the list, however any identifying information will be redacted. This can be useful if you want to display all sponsors, regardless of their privacy settings. | `with` | **No** |

#### 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.

| Status | Description |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `success` | The `success` status indicates that the action was able to successfully generate the README. |
| `failed` | The `failed` status indicates that the action encountered an error while trying to generate the README. |
| `skipped` | The `skipped` status indicates that the action could not locate the markers in your .md file. |
| `running` | The `running` status indicates that the action is actively working. |

---

### 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.

| Status | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | The users full name. This can sometimes be `null` if the user hasn't set one. This can be accessed using `{{ name }}` |
| `login` | The users login, this can be accessed using `{{ login }}` |
| `url` | The users GitHub profile url, this can be accessed using `{{ url }}`. |
| `avatarUrl` | The users avatar url, this can be accessed using `{{ avatarUrl }}`. |
| `websiteUrl` | The users website url. This can sometimes be `null` if the user hasn't set one, if so this field will fall back to `url`. This can be accessed using `{{ websiteUrl }}`. |

You're able to use markdown or GitHub approved basic HTML. The default template can be found [here](./src/constants.ts#L38).

You can view a full example of this here.

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

```md
# Awesome Project

Go you!

## Sponsors

These are our really cool 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.

You can view a full example of this here.

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

```md
# Awesome Project

Go you!

## Gold Sponsors

## Silver Sponsors

```