This is a GitHub Action that given an organization or specified repositories, produces information about the contributors over the specified time period.
Similar actions to help you recognize contributors by putting them into a README
or CONTRIBUTORS.md
include:
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.
If you need support using this project or have questions about it, please open 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 through issues 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 the GitHub API documentation.
.github/workflows/
directory with the file extension .yml
(ie. .github/workflows/contributors.yml
)ORGANIZATION
, REPOSITORY
, START_DATE
, END_DATE
) from the sample workflow with your information.
GH_ENTERPRISE_URL
if you are using a GitHub Server and not using github.com. For github.com users, don't put anything in here.GH_TOKEN
.
GH_TOKEN
and the value of the secret the API token.GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
to GH_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.token: ${{ secrets.GITHUB_TOKEN }}
with your own GitHub API token stored as a repository secret.
master
or main
)schedule
entry or manually trigger the workflow as shown in the documentation.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:
field | required | default | description |
---|---|---|---|
GH_APP_ID |
True | "" |
GitHub Application ID. See documentation for more details. |
GH_APP_INSTALLATION_ID |
True | "" |
GitHub Application Installation ID. See documentation for more details. |
GH_APP_PRIVATE_KEY |
True | "" |
GitHub Application Private Key. See documentation for more details. |
field | required | default | description |
---|---|---|---|
GH_TOKEN |
True | "" |
The GitHub Token used to scan the repository. Must have read access to all repository you are interested in scanning. |
field | required | default | description |
---|---|---|---|
GH_ENTERPRISE_URL |
False | "" | The GH_ENTERPRISE_URL is used to connect to an enterprise server instance of GitHub. github.com users should not enter anything here. |
ORGANIZATION |
Required to have ORGANIZATION or REPOSITORY |
The name of the GitHub organization which you want the contributor information of all repos from. ie. github.com/github would be github |
|
REPOSITORY |
Required to have ORGANIZATION or REPOSITORY |
The name of the repository and organization which you want the contributor information from. ie. github/contributors or a comma separated list of multiple repositories github/contributor,super-linter/super-linter |
|
START_DATE |
False | Beginning of time | The date from which you want to start gathering contributor information. ie. Aug 1st, 2023 would be 2023-08-01 . |
END_DATE |
False | Current Date | The date at which you want to stop gathering contributor information. Must be later than the START_DATE . ie. Aug 2nd, 2023 would be 2023-08-02 |
SPONSOR_INFO |
False | False | If you want to include sponsor information in the output. This will include the sponsor count and the sponsor URL. This will impact action performance. ie. SPONSOR_INFO = "False" or SPONSOR_INFO = "True" |
LINK_TO_PROFILE |
False | True | If you want to link usernames to their GitHub profiles in the output. ie. LINK_TO_PROFILE = "True" or LINK_TO_PROFILE = "False" |
Note: If start_date
and end_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 report
on:
workflow_dispatch:
schedule:
- cron: "3 2 1 * *"
permissions:
contents: read
jobs:
contributor_report:
name: contributor report
runs-on: ubuntu-latest
permissions:
issues: write
steps:
- name: Get dates for last month
shell: bash
run: |
# 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 action
uses: github/contributors@v1
env:
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 issue
uses: peter-evans/create-issue-from-file@v5
with:
title: Monthly contributor report
token: ${{ secrets.GITHUB_TOKEN }}
content-filepath: ./contributors.md
assignees: <YOUR_GITHUB_HANDLE_HERE>
start_date
and end_date
supplied# 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) |
.env-example
to .env
.env
file with a token 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..env
file with the configuration parameters you want to usepip3 install -r requirements.txt
python3 ./contributors.py
, which will output everything in the terminalLooking for more resources for your open source program office (OSPO)? Check out the github-ospo
repo for a variety of tools designed to support your needs.