Merge pull request #197 from ricardojdsilva87/feat/support-github-enterprise-api

feat: support GitHub enterprise api

Author: jmeridth

.coveragerc

@@ -0,0 +1,4 @@
+[run]
+omit =
+    # omit test files
+    test_*.py

.env-example

@@ -1,4 +1,4 @@
-GH_ENTERPRISE_URL=""
+GH_ENTERPRISE_URL = ""
 GH_TOKEN = ""
 END_DATE = ""
 ORGANIZATION = "organization"
@@ -9,3 +9,4 @@ START_DATE = ""
 GH_APP_ID = ""
 GH_INSTALLATION_ID = ""
 GH_PRIVATE_KEY = ""
+GITHUB_APP_ENTERPRISE_ONLY = ""

README.md

@@ -38,11 +38,19 @@ Find out more in the [GitHub API documentation](https://docs.github.com/en/rest/
 1. Create a repository to host this GitHub Action or select an existing repository.
 1. Select a best fit workflow file from the [examples below](#example-workflows).
 1. 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`)
-1. Edit the values (`ORGANIZATION`, `REPOSITORY`, `START_DATE`, `END_DATE`) from the sample workflow with your information.
-   - If no start 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 whole organization then no repository is needed.
-   - If running the action on just one repository or a list of repositories, then no organization is needed.
-1. Also edit the value for `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.
+1. Edit the values below from the sample workflow with your information:
+
+   - `ORGANIZATION`
+   - `REPOSITORY`
+   - `START_DATE`
+   - `END_DATE`
+
+   If no **start 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 whole **organization** then no repository is needed.  
+   If running the action on just **one repository** or a **list of repositories**, then no organization is needed.
+
+1. Also edit the value for `GH_ENTERPRISE_URL` if you are using a GitHub Server and not using github.com.  
+   For github.com users, leave it empty.
 1. 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 of `GH_TOKEN`.
    - Do this by creating a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with permissions to read the repository/organization and write issues.
    - Then take the value of the API token you just created, and [create a repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) where the name of the secret is `GH_TOKEN` and the value of the secret the API token.
@@ -62,11 +70,12 @@ This action can be configured to authenticate with GitHub App Installation or Pe
 
 ##### GitHub App Installation
 
-| field                    | required | default | description                                                                                                                                                                                             |
-| ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GH_APP_ID`              | True     | `""`    | GitHub Application ID. See [documentation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) for more details.              |
-| `GH_APP_INSTALLATION_ID` | True     | `""`    | GitHub Application Installation ID. See [documentation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) for more details. |
-| `GH_APP_PRIVATE_KEY`     | True     | `""`    | GitHub Application Private Key. See [documentation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) for more details.     |
+| field                        | required | default | description                                                                                                                                                                                             |
+| ---------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GH_APP_ID`                  | True     | `""`    | GitHub Application ID. See [documentation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) for more details.              |
+| `GH_APP_INSTALLATION_ID`     | True     | `""`    | GitHub Application Installation ID. See [documentation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) for more details. |
+| `GH_APP_PRIVATE_KEY`         | True     | `""`    | GitHub Application Private Key. See [documentation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) for more details.     |
+| `GITHUB_APP_ENTERPRISE_ONLY` | False    | false   | Set this input to `true` if your app is created in GHE and communicates with GHE.                                                                                                                       |
 
 ##### Personal Access Token (PAT)
 
@@ -143,6 +152,62 @@ jobs:
           assignees: <YOUR_GITHUB_HANDLE_HERE>
 ```
 
+#### Using GitHub app
+
+```yaml
+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_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 api
+          GH_ENTERPRISE_URL: ${{ github.server_url }}
+          # GH_TOKEN: ${{ steps.app-token.outputs.token }} --> the token input is not used if the github app inputs are set
+          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>
+```
+
 ## Example Markdown output with `start_date` and `end_date` supplied
 
 ```markdown

auth.py

@@ -1,36 +1,42 @@
 """This is the module that contains functions related to authenticating to GitHub with a personal access token."""
 
 import github3
+import requests
 
 
 def auth_to_github(
-    gh_app_id: str,
-    gh_app_installation_id: int,
-    gh_app_private_key_bytes: bytes,
     token: str,
+    gh_app_id: int | None,
+    gh_app_installation_id: int | None,
+    gh_app_private_key_bytes: bytes,
     ghe: str,
+    gh_app_enterprise_only: bool,
 ) -> github3.GitHub:
     """
     Connect to GitHub.com or GitHub Enterprise, depending on env variables.
 
     Args:
-        gh_app_id (str): the GitHub App ID
-        gh_installation_id (int): the GitHub App Installation ID
-        gh_app_private_key (bytes): the GitHub App Private Key
         token (str): the GitHub personal access token
+        gh_app_id (int | None): the GitHub App ID
+        gh_app_installation_id (int | None): the GitHub App Installation ID
+        gh_app_private_key_bytes (bytes): the GitHub App Private Key
         ghe (str): the GitHub Enterprise URL
+        gh_app_enterprise_only (bool): Set this to true if the GH APP is created on GHE and needs to communicate with GHE api only
 
     Returns:
         github3.GitHub: the GitHub connection object
     """
     if gh_app_id and gh_app_private_key_bytes and gh_app_installation_id:
-        gh = github3.github.GitHub()
+        if ghe and gh_app_enterprise_only:
+            gh = github3.github.GitHubEnterprise(url=ghe)
+        else:
+            gh = github3.github.GitHub()
         gh.login_as_app_installation(
             gh_app_private_key_bytes, gh_app_id, gh_app_installation_id
         )
         github_connection = gh
     elif ghe and token:
-        github_connection = github3.github.GitHubEnterprise(ghe, token=token)
+        github_connection = github3.github.GitHubEnterprise(url=ghe, token=token)
     elif token:
         github_connection = github3.login(token=token)
     else:
@@ -41,3 +47,35 @@ def auth_to_github(
     if not github_connection:
         raise ValueError("Unable to authenticate to GitHub")
     return github_connection  # type: ignore
+
+
+def get_github_app_installation_token(
+    ghe: str,
+    gh_app_id: str,
+    gh_app_private_key_bytes: bytes,
+    gh_app_installation_id: str,
+) -> str | None:
+    """
+    Get a GitHub App Installation token.
+    API: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation
+
+    Args:
+        ghe (str): the GitHub Enterprise endpoint
+        gh_app_id (str): the GitHub App ID
+        gh_app_private_key_bytes (bytes): the GitHub App Private Key
+        gh_app_installation_id (str): the GitHub App Installation ID
+
+    Returns:
+        str: the GitHub App token
+    """
+    jwt_headers = github3.apps.create_jwt_headers(gh_app_private_key_bytes, gh_app_id)
+    api_endpoint = f"{ghe}/api/v3" if ghe else "https://api.github.com"
+    url = f"{api_endpoint}/app/installations/{gh_app_installation_id}/access_tokens"
+
+    try:
+        response = requests.post(url, headers=jwt_headers, json=None, timeout=5)
+        response.raise_for_status()
+    except requests.exceptions.RequestException as e:
+        print(f"Request to get GitHub App Installation Token failed: {e}")
+        return None
+    return response.json().get("token")

contributor_stats.py

@@ -114,9 +114,7 @@ def merge_contributors(contributors: list) -> list:
                         )
                         # Merge the commit urls via concatenation
                         merged_contributor.commit_url = (
-                            merged_contributor.commit_url
-                            + ", "
-                            + contributor.commit_url
+                            f"{merged_contributor.commit_url}, {contributor.commit_url}"
                         )
                         # Merge the new_contributor attribute via OR
                         merged_contributor.new_contributor = (
@@ -130,7 +128,7 @@ def merge_contributors(contributors: list) -> list:
     return merged_contributors
 
 
-def get_sponsor_information(contributors: list, token: str) -> list:
+def get_sponsor_information(contributors: list, token: str, ghe: str) -> list:
     """
     Get the sponsor information for each contributor
 
@@ -155,9 +153,10 @@ def get_sponsor_information(contributors: list, token: str) -> list:
         variables = {"username": contributor.username}
 
         # Send the GraphQL request
+        api_endpoint = f"{ghe}/api/v3" if ghe else "https://api.github.com"
         headers = {"Authorization": f"Bearer {token}"}
         response = requests.post(
-            "https://api.github.com/graphql",
+            f"{api_endpoint}/graphql",
             json={"query": query, "variables": variables},
             headers=headers,
             timeout=60,
@@ -169,10 +168,9 @@ def get_sponsor_information(contributors: list, token: str) -> list:
 
         data = response.json()["data"]
 
+        endpoint = ghe if ghe else "https://github.com"
         # if the user has a sponsor page, add it to the contributor object
         if data["repositoryOwner"]["hasSponsorsListing"]:
-            contributor.sponsor_info = (
-                f"https://github.com/sponsors/{contributor.username}"
-            )
+            contributor.sponsor_info = f"{endpoint}/sponsors/{contributor.username}"
 
     return contributors

contributors.py

@@ -19,7 +19,8 @@ def main():
         repository_list,
         gh_app_id,
         gh_app_installation_id,
-        gh_app_private_key_bytes,
+        gh_app_private_key,
+        gh_app_enterprise_only,
         token,
         ghe,
         start_date,
@@ -30,16 +31,22 @@ def main():
 
     # Auth to GitHub.com
     github_connection = auth.auth_to_github(
-        gh_app_id, gh_app_installation_id, gh_app_private_key_bytes, token, ghe
+        token,
+        gh_app_id,
+        gh_app_installation_id,
+        gh_app_private_key,
+        ghe,
+        gh_app_enterprise_only,
     )
 
+    if not token and gh_app_id and gh_app_installation_id and gh_app_private_key:
+        token = auth.get_github_app_installation_token(
+            ghe, gh_app_id, gh_app_private_key, gh_app_installation_id
+        )
+
     # Get the contributors
     contributors = get_all_contributors(
-        organization,
-        repository_list,
-        start_date,
-        end_date,
-        github_connection,
+        organization, repository_list, start_date, end_date, github_connection, ghe
     )
 
     # Check for new contributor if user provided start_date and end_date
@@ -52,6 +59,7 @@ def main():
             start_date="2008-02-29",  # GitHub was founded on 2008-02-29
             end_date=start_date,
             github_connection=github_connection,
+            ghe=ghe,
         )
         for contributor in contributors:
             contributor.new_contributor = contributor_stats.is_new_contributor(
@@ -60,7 +68,9 @@ def main():
 
     # Get sponsor information on the contributor
     if sponsor_info == "true":
-        contributors = contributor_stats.get_sponsor_information(contributors, token)
+        contributors = contributor_stats.get_sponsor_information(
+            contributors, token, ghe
+        )
     # Output the contributors information
     # print(contributors)
     markdown.write_to_markdown(
@@ -72,6 +82,7 @@ def main():
         repository_list,
         sponsor_info,
         link_to_profile,
+        ghe,
     )
     json_writer.write_to_json(
         filename="contributors.json",
@@ -91,6 +102,7 @@ def get_all_contributors(
     start_date: str,
     end_date: str,
     github_connection: object,
+    ghe: str,
 ):
     """
     Get all contributors from the organization or repository
@@ -118,7 +130,7 @@ def get_all_contributors(
     all_contributors = []
     if repos:
         for repo in repos:
-            repo_contributors = get_contributors(repo, start_date, end_date)
+            repo_contributors = get_contributors(repo, start_date, end_date, ghe)
             if repo_contributors:
                 all_contributors.append(repo_contributors)
 
@@ -128,11 +140,7 @@ def get_all_contributors(
     return all_contributors
 
 
-def get_contributors(
-    repo: object,
-    start_date: str,
-    end_date: str,
-):
+def get_contributors(repo: object, start_date: str, end_date: str, ghe: str):
     """
     Get contributors from a single repository and filter by start end dates if present.
 
@@ -165,12 +173,11 @@ def get_contributors(
                     continue
 
             # Store the contributor information in a ContributorStats object
+            endpoint = ghe if ghe else "https://github.com"
             if start_date and end_date:
-                commit_url = f"https://github.com/{repo.full_name}/commits?author={user.login}&since={start_date}&until={end_date}"
+                commit_url = f"{endpoint}/{repo.full_name}/commits?author={user.login}&since={start_date}&until={end_date}"
             else:
-                commit_url = (
-                    f"https://github.com/{repo.full_name}/commits?author={user.login}"
-                )
+                commit_url = f"{endpoint}/{repo.full_name}/commits?author={user.login}"
             contributor = contributor_stats.ContributorStats(
                 user.login,
                 False,
@@ -181,7 +188,7 @@ def get_contributors(
             )
             contributors.append(contributor)
     except Exception as e:
-        print("Error getting contributors for repository: " + repo.full_name)
+        print(f"Error getting contributors for repository: {repo.full_name}")
         print(e)
         return None