feat: Add GitHub Actions Job Summary support for contributor reports

README.md

@@ -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

markdown.py

@@ -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,
@@ -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
@@ -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 " f"{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):