Skip to content

feat: Add GitHub Actions Job Summary support for contributor reports #314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
+248 −58
Open

feat: Add GitHub Actions Job Summary support for contributor reports #314

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b5a3d1
Initial plan
Copilot Aug 20, 2025
c7c4b16
Add GitHub Actions Job Summary support
Copilot Aug 20, 2025
be2d2d2
Add documentation for GitHub Actions Job Summary feature
Copilot Aug 20, 2025
6405638
Fix linting issues in GitHub Actions Job Summary implementation
Copilot Aug 20, 2025
78b07ef
Fix pylint unused-argument warnings in test_markdown.py
Copilot Aug 20, 2025
a2119f7
fix: use single f-string
zkoppert Aug 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,12 @@ jobs:
| @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) |
```

## GitHub Actions Job Summary

When running as a GitHub Action, the contributors report is automatically displayed in the [GitHub Actions Job Summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). This provides immediate visibility of the results directly in the workflow run interface without needing to check separate files or issues.

The job summary contains the same markdown content that is written to the `contributors.md` file, making it easy to view contributor information right in the GitHub Actions UI.

## Local usage without Docker

1. Make sure you have at least Python3.11 installed
Expand Down
174 changes: 140 additions & 34 deletions markdown.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# pylint: disable=too-many-locals
"""This module contains the functions needed to write the output to markdown files."""

import os


def write_to_markdown(
collaborators,
Expand All @@ -15,18 +17,27 @@ def write_to_markdown(
):
"""
This function writes a list of collaborators to a markdown file in table format.
Each collaborator is represented as a dictionary with keys 'username', 'contribution_count', 'new_contributor', and 'commits'.
Each collaborator is represented as a dictionary with keys 'username',
'contribution_count', 'new_contributor', and 'commits'.

Args:
collaborators (list): A list of dictionaries, where each dictionary represents a collaborator.
Each dictionary should have the keys 'username', 'contribution_count', and 'commits'.
filename (str): The path of the markdown file to which the table will be written.
start_date (str): The start date of the date range for the contributor list.
collaborators (list): A list of dictionaries, where each dictionary
represents a collaborator. Each dictionary should
have the keys 'username', 'contribution_count',
and 'commits'.
filename (str): The path of the markdown file to which the table will
be written.
start_date (str): The start date of the date range for the contributor
list.
end_date (str): The end date of the date range for the contributor list.
organization (str): The organization for which the contributors are being listed.
repository (str): The repository for which the contributors are being listed.
sponsor_info (str): True if the user wants the sponsor_url shown in the report
link_to_profile (str): True if the user wants the username linked to Github profile in the report
organization (str): The organization for which the contributors are
being listed.
repository (str): The repository for which the contributors are being
listed.
sponsor_info (str): True if the user wants the sponsor_url shown in
the report
link_to_profile (str): True if the user wants the username linked to
Github profile in the report

Returns:
None
Expand All @@ -44,52 +55,147 @@ def write_to_markdown(
ghe,
)

# Put together the summary table including # of new contributions, # of new contributors, % new contributors, % returning contributors
# Put together the summary table including # of new contributions,
# # of new contributors, % new contributors, % returning contributors
summary_table = get_summary_table(
collaborators, start_date, end_date, total_contributions
)

# Write the markdown file
write_markdown_file(
filename, start_date, end_date, organization, repository, table, summary_table
filename,
start_date,
end_date,
organization,
repository,
table,
summary_table,
)

# Also write to GitHub Actions Step Summary if available
write_to_github_summary(
start_date, end_date, organization, repository, table, summary_table
)


def write_to_github_summary(
start_date, end_date, organization, repository, table, summary_table
):
"""
Write markdown content to GitHub Actions Step Summary.

Args:
start_date (str): The start date of the date range for the contributor
list.
end_date (str): The end date of the date range for the contributor list.
organization (str): The organization for which the contributors are
being listed.
repository (str): The repository for which the contributors are being
listed.
table (str): A string containing a markdown table of the contributors
and the total contribution count.
summary_table (str): A string containing a markdown table of the
summary statistics.

Returns:
None
"""
# Only write to GitHub Step Summary if we're running in a GitHub Actions
# environment
github_step_summary = os.environ.get("GITHUB_STEP_SUMMARY")
if github_step_summary:
content = generate_markdown_content(
start_date,
end_date,
organization,
repository,
table,
summary_table,
)
with open(github_step_summary, "a", encoding="utf-8") as summary_file:
summary_file.write(content)


def generate_markdown_content(
start_date, end_date, organization, repository, table, summary_table
):
"""
This function generates markdown content as a string.

Args:
start_date (str): The start date of the date range for the contributor
list.
end_date (str): The end date of the date range for the contributor list.
organization (str): The organization for which the contributors are
being listed.
repository (str): The repository for which the contributors are being
listed.
table (str): A string containing a markdown table of the contributors
and the total contribution count.
summary_table (str): A string containing a markdown table of the
summary statistics.

Returns:
str: The complete markdown content as a string.

"""
content = "# Contributors\n\n"
if start_date and end_date:
content += (
f"- Date range for contributor list: {start_date} to {end_date}\n"
)
if organization:
content += f"- Organization: {organization}\n"
if repository:
content += f"- Repository: {repository}\n"
content += "\n"
content += summary_table
content += table
content += (
"\n _this file was generated by the "
"[Contributors GitHub Action]"
"(https://github.com/github/contributors)_\n"
)
return content


def write_markdown_file(
filename, start_date, end_date, organization, repository, table, summary_table
filename,
start_date,
end_date,
organization,
repository,
table,
summary_table,
):
"""
This function writes all the tables and data to a markdown file with tables to organizae the information.
This function writes all the tables and data to a markdown file with
tables to organize the information.

Args:
filename (str): The path of the markdown file to which the table will be written.
start_date (str): The start date of the date range for the contributor list.
filename (str): The path of the markdown file to which the table will
be written.
start_date (str): The start date of the date range for the contributor
list.
end_date (str): The end date of the date range for the contributor list.
organization (str): The organization for which the contributors are being listed.
repository (str): The repository for which the contributors are being listed.
table (str): A string containing a markdown table of the contributors and the total contribution count.
summary_table (str): A string containing a markdown table of the summary statistics.
organization (str): The organization for which the contributors are
being listed.
repository (str): The repository for which the contributors are being
listed.
table (str): A string containing a markdown table of the contributors
and the total contribution count.
summary_table (str): A string containing a markdown table of the
summary statistics.

Returns:
None

"""
content = generate_markdown_content(
start_date, end_date, organization, repository, table, summary_table
)
with open(filename, "w", encoding="utf-8") as markdown_file:
markdown_file.write("# Contributors\n\n")
if start_date and end_date:
markdown_file.write(
f"- Date range for contributor list: {start_date} to {end_date}\n"
)
if organization:
markdown_file.write(f"- Organization: {organization}\n")
if repository:
markdown_file.write(f"- Repository: {repository}\n")
markdown_file.write("\n")
markdown_file.write(summary_table)
markdown_file.write(table)
markdown_file.write(
"\n _this file was generated by the [Contributors GitHub Action](https://github.com/github/contributors)_\n"
)
markdown_file.write(content)


def get_summary_table(collaborators, start_date, end_date, total_contributions):
Expand Down
Loading
Loading