Contributors Forks Stargazers Issues MIT License


Contributors-Readme-Action is a simple GitHub action to automate contributors list in README file. Not only contributors, collborators, bots or any user.

As it uses a GitHub action it's secure and very easy to integrate into your projects. Once added it will automatically add all the repository contributors to your readme in a well-formatted table, including future contributors 😄. Now why would you need a contributors list? Come on man, show some love to the ones who contribute to your project.😉

The contributors list is fetched from GitHub API.

Getting Started

First Step

If you're new to actions, add these to your .github/workflows/main.yml file. If this file does not exist, create one.

on: [push, pull_request]

        runs-on: ubuntu-latest
        name: A job to automate contrib in readme
            - name: Contribute List
              uses: akhilmhdh/contributors-readme-[email protected]
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

That's it!

To add it to your to your existing workflow, append this to your current .yml workflow script.

- uses: akhilmhdh/contributors-readme-[email protected]
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Currently GITHUB_TOKEN doesn't have permission to directly commit on a protected branch. To solve this you may need to replace the github action token with an admin acc token as mentioned in this post by phips28. Hopefully in the future GitHub can give an exception to actions in workflow.

Now there is an alternative solution, if your branch is protected or there is status checks. You can set input is_protected to true in config and the action won't directly commit to the branch. Instead it will put a PR by creating a branch out of the branch that the action is running on. To avoid bloating with lot of branches either delete the branch on merge or set the option in github to delete source branch on merge automatically.

Second Step

  1. Add a file
  2. Add the below comment inside your where you want it to appear.
<!-- readme: contributors -start -->
<!-- readme: contributors -end -->
  1. Save it, wait for the action to complete and tadaa 😄

But wait!!!

  • What if you wanted to add direct collaborators of a project, no worries
## Collaborators

<!-- readme: collaborators -start -->
<!-- readme: collaborators -end -->

## Contributors

<!-- readme: contributors -start -->
<!-- readme: contributors -end -->
  • Now you decided that you want to join this into one list, no issue
## Contributors

<!-- readme: collaborators,contributors -start -->
<!-- readme: collaborators,contributors -end -->
  • Then you decided to add some github users who are important figure in this project
## Contributors

<!-- readme: <username1>,collaborators,<username2>,contributors -start -->
<!-- readme: <username1>,collaborators,<username3>,contributors -end -->

The order of the list will be given priority. So username1 will appear first collaborators then username2 likewise.(No brackets for usernames)

The subject inside start and end must be same.


contributorscontributors of the repo
collaboratorscontributors of the repo
sponsorssponsors of the repo's user/organization
botsbots of the repo
usernameany username that you want to add on to the list


Operators are in a nutshell simple modifiers that can be applied to a list like removing a person from a list. They can be applied accordingly to a keyword like akhilmhdh/- with a / as seperator.

/-remove the username from listakhilmhdh/-

Optional parameters

You can add these optional parameters in your action script to modify the appearance of the resulting list.

- name: Contribute List
  uses: akhilmhdh/contributors-readme-[email protected]
      image_size: 100
OptionDefault ValueDescriptionRequired
image_size100(px)Size of square images in the stackfalse
is_protectedfalseIf the branch to be updated is protected change this to true to change from directly commiting to PR updatefalse
readme_pathREADME.mdPath of the readme file you want to updatefalse
user_usernamefalseTo use username instead of full namefalse
columns_per_row6Number of columns in a rowfalse
collaboratorsdirectType of collaborators options: all/direct/outsidefalse
commit_messagecontrib-readme-action has updated readmeCommit message of the github actionfalse
committer_usernamecontrib-readme-botUsername on commitfalse
committer_emailemail id of committer[email protected]false


This project is licensed under the MIT License - see the LICENSE file for details.