minicli / action-contributors

GitHub Action to dynamically update CONTRIBUTORS file

Generate / Update CONTRIBUTORS File - GitHub Action

This GitHub Action updates a CONTRIBUTORS file with the top contributors from the specified project, pulling contents from the GitHub API. You can use it in combination with an action to push changes directly into your project's main branch, or with an action that creates a PR with the updated file.

Supported Configuration via Environment Variables:

• CONTRIB_REPOSITORY: The repository you want to pull contributors from. This is mandatory.
• CONTRIB_OUTPUT_FILE: The file you want to generate, default set to CONTRIBUTORS.md.
• CONTRIB_STENCIL_DIR: Where to find Stencil templates. Default set to .stencil.
• CONTRIB_TEMPLATE: The stencil template to use - you can use this to customize the generated markdown file. Default set to the included contributors.tpl file.
• CONTRIB_IGNORE: A comma-separated string with users to ignore. Default set to github-actions[bot],renovate-bot,dependabot.

Basic Usage

This action is made to use in conjunction with test-room-7/action-update-file in order to automatically commit an updated CONTRIBUTORS file in a fixed interval.

The following example sets a workflow to update the file once a month, committing the changes directly to the main project's branch:

name: Update CONTRIBUTORS file
on:
  schedule:
    - cron: "0 0 1 * *"
  workflow_dispatch:
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: minicli/[email protected]
        name: "Update a projects CONTRIBUTORS file"
        env:
          CONTRIB_REPOSITORY: 'minicli/minicli'
          CONTRIB_OUTPUT_FILE: 'CONTRIBUTORS.md'
      - name: Commit changes
        uses: test-room-7/action-update-file@v1
        with:
          file-path: 'CONTRIBUTORS.md'
          commit-msg: Update Contributors
          github-token: ${{ secrets.GITHUB_TOKEN }}

You need to replace the CONTRIB_REPOSITORY value with the GitHub project you want to pull contributors from.

If you'd prefer to create a pull request instead of committing the changes directly to the main branch, you can use the create-pull-request action instead. That will require also the actions/checkout GitHub action.

name: Update CONTRIBUTORS file
on:
  schedule:
    - cron: "0 0 1 * *"
  workflow_dispatch:
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: minicli/[email protected]
        name: "Update a projects CONTRIBUTORS file"
        env:
          CONTRIB_REPOSITORY: 'minicli/docs'
          CONTRIB_OUTPUT_FILE: 'CONTRIBUTORS.md'
      - name: Create a PR
        uses: peter-evans/create-pull-request@v3
        with:
          commit-message: Update Contributors
          title: "[automated] Update Contributors File"
          token: ${{ secrets.GITHUB_TOKEN }}

Using a Custom Template

This action uses a simple templating lib that allows some customization for the final generated markdown file.

Here's how the default template looks like:

# Top Contributors: {{ repo }}
Shout out to our top contributors!

{{ content }}

_Last updated: {{ updated }}_

The app will pass on the following variables to the template, which you can use as you prefer:

• repo: the repository from where the data is coming from. Ex: minicli/minicli
• content: the full list of contributors
• updated: date and time the file was generated in RFC822 format

To use a custom template, create a .tpl file based on the default template. Then, include the following environment variables on your workflow:

• CONTRIB_STENCIL_DIR: a directory in your workflow repository where you'll have your template(s). Set this as ${{ github.workspace }}/YOUR_DIRECTORY
• CONTRIB_TEMPLATE: the name of the file, without the tpl extension. Default: contributors

This template file must be committed to the same repository where the workflow is defined.

Then, you'll also need to include the actions/checkout action to your workflow so that your repo files are available to the GitHub runner when it executes the action.

Here is an example of a workflow that uses a custom template called mytemplate.tpl, located in a .stencil directory in the repository where the workflow is set:

name: Update CONTRIBUTORS file
on:
  schedule:
    - cron: "0 0 1 * *"
  workflow_dispatch:
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: minicli/[email protected]
        name: "Update a projects CONTRIBUTORS file"
        env:
          CONTRIB_REPOSITORY: 'minicli/minicli'
          CONTRIB_OUTPUT_FILE: 'CONTRIBUTORS.md'
          CONTRIB_STENCIL_DIR: ${{ github.workspace }}/.stencil
          CONTRIB_TEMPLATE: mytemplate
      - name: Commit changes
        uses: test-room-7/action-update-file@v1
        with:
          file-path: 'CONTRIBUTORS.md'
          commit-msg: Update Contributors
          github-token: ${{ secrets.GITHUB_TOKEN }}

action-contributors's Issues

Missing the Code of Conduct

Hello,
This project is currently missing the Code of Conduct. I am not sure if you would be interested in adding one, but if you do, then please let me know so that I can add a PR for that. And yeah, in that case, I would also need an address (email address) for adding that in the Code of Conduct file.

Suggested feature: Last contribution

Just saw this on LinkedIn. Surprised to see some PHP in here. Hello 👋 😆

One thing I notice in some repo's is that it's hard to see who is an active contributor, versus a legacy maintainer, who may have lost interest in a project. This can lead to legacy maintainers getting contacted about projects they are no longer involved in, and confusion as to who the active and current team are.

It would be interesting if there was a way to show the last contribution date (maybe even PR) in the generated contributors file.

I don't expect this to be added. It's just an idea, and I wondered if placing it here might see interest from others. Thank you.

Commits only changing "Last updated" line are polluting commit history

I run the action every night to add new contributors. But if there are no new contributors, it still creates a commit with just an updated "Last updated" line.

Example: komunumo/komunumo-server@8c99850

If there are no new contributors, I would not expect to update the file at all.

Guide to run project locally

No doubt the project is is great, just the issue is PHP is not everyone's cup of tea.

Can you please add a guide how can we run/test the project locally and make the changes to get a more effective and beautiful contributors.md file.

Right now I just have an idea to add a check on workflow of the action to check and commit changes to the contributors.md file only if there's a new contributor added to the mentioned repository otherwise just pass the workflow. But it would be great for all of us if you could add a guide to run this project locally so that we can also contribute to it.

(I am assuming that this check is not added yet because of the same reason PHP xD)

Incomplete contributors list?

KhronosGroup/Vulkan-ValidationLayers#5246

Trying to integrate this into our project. As shown in this PR the list is incomplete. Our repo has 287 contributors in total.

But only about 30 are showing.

Breaking the action into two repositories?

Currently, the app that is executed within this GitHub Action is self-contained within the Action repository. This was convenient at first, but if the app gains more features and starts to become more complex, I'm starting to think that it would be better to have it on its own repository. Maybe some people would rather run the app manually or on a self-hosted environment.

Anyone has thoughts on that?

File is not created if it doesn't exist

If there is no contributors file, it won't create but it will tell the action ran succesfully.

Custom template not working

The directions to set up a custom template are not working as expected. Stencil expects a template directory that must be set before setting the template name. We'll need a second ENV var to set the directory, otherwise we'll need to change how Stencil works.

Working on it.

Wrong GitHub profile link

After using your action (thank you very much for automating this task), the profile links in the CONTRIBUTORS.md are broken. They point to an API call instead of the profile page:

Actual: https://api.github.com/users/McPringle
Expected: https://github.com/McPringle

As a result, if the viewer of the file clicks on the GitHub username, he will get a JSON file instead of the expected profile page.

Filter renovate-bot

Please filter the @renovate-bot from the contributors. Or add a configuration option to configure usernames to exclude (there might be a lot more bot out there).