Repository files navigation

This is a GitHub Action that given an organization or specified repositories, produces information about thecontributors over the specified time period.

Similar actions to help you recognize contributors by putting them into aREADME orCONTRIBUTORS.md include:

• contributor-list

This action was developed by the GitHub OSPO for our own use and developed in a way that we could open source it that it might be useful to you as well! If you want to know more about how we use it, reach out in an issue in this repository.

• As a maintainer, you may want to acknowledge recent contributors in a discussion post
• As an OSPO or maintainer, you may want to know who candidates are for new maintainers

If you need support using this project or have questions about it, pleaseopen up an issue in this repository. Requests made directly to GitHub staff or support team will be redirected here to open an issue. GitHub SLA's and support/services contracts do not apply to this repository.

All feedback regarding our GitHub Actions, as a whole, should be communicated throughissues on our github-ospo repository.

Contributors have made commits to the specified repositories/organization on a default branch. Contributions can also be issue, pull request and discussion interactions. The endpoint used may return information that is a few hours old because the GitHub REST API caches contributor data to improve performance.

GitHub identifies contributors by author email address. Contribution counts are grouped by GitHub user, which includes all associated email addresses. To improve performance, only the first 500 author email addresses in the repository link to GitHub users. The rest will appear as anonymous contributors without associated GitHub user information.

Find out more in theGitHub API documentation.

1. Create a repository to host this GitHub Action or select an existing repository.

2. Select a best fit workflow file from theexamples below.

3. Copy that example into your repository (from step 1) and into the proper directory for GitHub Actions:.github/workflows/ directory with the file extension.yml (ie..github/workflows/contributors.yml)

4. Edit the values below from the sample workflow with your information:

   • ORGANIZATION
   • REPOSITORY
   • START_DATE
   • END_DATE

   If nostart and end date are supplied, the action will consider the entire repository history and be unable to determine if contributors are new or returning.If running on a wholeorganization then no repository is needed.
   If running the action on justone repository or alist of repositories, then no organization is needed.

5. Also edit the value forGH_ENTERPRISE_URL if you are using a GitHub Server and not using github.com.
   For github.com users, leave it empty.

6. If you are running this action on an organization or repository other than the one where the workflow file is going to be, then update the value ofGH_TOKEN.

   • Do this by creating aGitHub API token with permissions to read the repository/organization and write issues.
   • Then take the value of the API token you just created, andcreate a repository secret where the name of the secret isGH_TOKEN and the value of the secret the API token.
   • Then finally update the workflow file to use that repository secret by changingGH_TOKEN: ${{ secrets.GITHUB_TOKEN }} toGH_TOKEN: ${{ secrets.GH_TOKEN }}. The name of the secret can really be anything. It just needs to match between when you create the secret name and when you refer to it in the workflow file.

7. If you want the resulting issue with the output to appear in a different repository other than the one the workflow file runs in, update the linetoken: ${{ secrets.GITHUB_TOKEN }} with your own GitHub API token stored as a repository secret.

   • This process is the same as described in the step above. More info on creating secrets can be foundhere.

8. Commit the workflow file to the default branch (oftenmaster ormain)

9. Wait for the action to trigger based on theschedule entry or manually trigger the workflow as shown in thedocumentation.

Below are the allowed configuration options:

This action can be configured to authenticate with GitHub App Installation or Personal Access Token (PAT). If all configuration options are provided, the GitHub App Installation configuration has precedence. You can choose one of the following methods to authenticate:

Note: Ifstart_date andend_date are specified then the action will determine if the contributor is new. A new contributor is one that has contributed in the date range specified but not before the start date.

Performance Note: Using start and end dates will reduce speed of the action by approximately 63X. ie without dates if the action takes 1.7 seconds, it will take 1 minute and 47 seconds.

Be sure to change at least these values:<YOUR_ORGANIZATION_GOES_HERE>,<YOUR_GITHUB_HANDLE_HERE>

name:Monthly contributor reporton:workflow_dispatch:schedule:    -cron:"3 2 1 * *"permissions:contents:readjobs:contributor_report:name:contributor reportruns-on:ubuntu-latestpermissions:issues:writesteps:      -name:Get dates for last monthshell:bashrun:|          # Calculate the first day of the previous month          start_date=$(date -d "last month" +%Y-%m-01)          # Calculate the last day of the previous month          end_date=$(date -d "$start_date +1 month -1 day" +%Y-%m-%d)          #Set an environment variable with the date range          echo "START_DATE=$start_date" >> "$GITHUB_ENV"          echo "END_DATE=$end_date" >> "$GITHUB_ENV"      -name:Run contributor actionuses:github/contributors@v1env:GH_TOKEN:${{ secrets.GITHUB_TOKEN }}START_DATE:${{ env.START_DATE }}END_DATE:${{ env.END_DATE }}ORGANIZATION:<YOUR_ORGANIZATION_GOES_HERE>SPONSOR_INFO:"true"      -name:Create issueuses:peter-evans/create-issue-from-file@v5with:title:Monthly contributor reporttoken:${{ secrets.GITHUB_TOKEN }}content-filepath:./contributors.mdassignees:<YOUR_GITHUB_HANDLE_HERE>

name:Monthly contributor reporton:workflow_dispatch:schedule:    -cron:"3 2 1 * *"permissions:contents:readjobs:contributor_report:name:contributor reportruns-on:ubuntu-latestpermissions:issues:writesteps:      -name:Get dates for last monthshell:bashrun:|          # Calculate the first day of the previous month          start_date=$(date -d "last month" +%Y-%m-01)          # Calculate the last day of the previous month          end_date=$(date -d "$start_date +1 month -1 day" +%Y-%m-%d)          #Set an environment variable with the date range          echo "START_DATE=$start_date" >> "$GITHUB_ENV"          echo "END_DATE=$end_date" >> "$GITHUB_ENV"      -name:Run contributor actionuses:github/contributors@v1env:GH_APP_ID:${{ secrets.GH_APP_ID }}GH_APP_INSTALLATION_ID:${{ secrets.GH_APP_INSTALLATION_ID }}GH_APP_PRIVATE_KEY:${{ secrets.GH_APP_PRIVATE_KEY }}# GITHUB_APP_ENTERPRISE_ONLY: True --> Set to true when created GHE App needs to communicate with GHE apiGH_ENTERPRISE_URL:${{ github.server_url }}# GH_TOKEN: ${{ steps.app-token.outputs.token }} --> the token input is not used if the github app inputs are setSTART_DATE:${{ env.START_DATE }}END_DATE:${{ env.END_DATE }}ORGANIZATION:<YOUR_ORGANIZATION_GOES_HERE>SPONSOR_INFO:"true"      -name:Create issueuses:peter-evans/create-issue-from-file@v5with:title:Monthly contributor reporttoken:${{ secrets.GITHUB_TOKEN }}content-filepath:./contributors.mdassignees:<YOUR_GITHUB_HANDLE_HERE>

#Contributors- Date range for contributor list: 2021-01-01 to 2023-10-10- Organization: super-linter| Total Contributors| Total Contributions| % new contributors|| ------------------| -------------------| ------------------|| 1| 143| 0%|| Username| All Time Contribution Count| New Contributor| Commits between 2021-01-01 and 2023-10-10|| ---------| ---------------------------| ---------------| -----------------------------------------------------------------------------------------------------------------------------------||@zkoppert| 143| False|[super-linter/super-linter](https://github.com/super-linter/super-linter/commits?author=zkoppert&since=2021-01-01&until=2023-10-10)|

####Contributors- Organization: super-linter| Total Contributors| Total Contributions| % new contributors|| ------------------| -------------------| ------------------|| 1| 1913| 0%|| Username| All Time Contribution Count| New Contributor| Sponsor URL| Commits between 2021-09-01 and 2023-09-30|| ---------| ---------------------------| ---------------| ----------------------------------------------------| -----------------------------------------------------------------------------------------------------------------------------------||@zkoppert| 1913| False|[Sponsor Link](https://github.com/sponsors/zkoppert)|[super-linter/super-linter](https://github.com/super-linter/super-linter/commits?author=zkoppert&since=2021-09-01&until=2023-09-30)|

1. Make sure you have at least Python3.11 installed
2. Copy.env-example to.env
3. Fill out the.env file with atoken from a user that has access to the organization to scan (listed below). Tokens should have at least read:org access for organization scanning and read:repository for repository scanning.
4. Fill out the.env file with the configuration parameters you want to use
5. pip3 install -r requirements.txt
6. Runpython3 ./contributors.py, which will output everything in the terminal

MIT

Looking for more resources for your open source program office (OSPO)? Check out thegithub-ospo repo for a variety of tools designed to support your needs.