Merge pull request #67 from SuffolkLITLab/user-feedback-label

Better logging of token permission issues

Author: nonprofittechy

README.md

@@ -101,6 +101,8 @@ This package is designed to support the following workflow:
    issue. This interview also will show you the list of emails of users who agreed to join a
    qualitative research panel.
 
+6. If the issue label "user feedback" is present on the repo, it will be used by default to label incoming issues.
+
 ## Author
 
 Quinten Steenhuis, qsteenhuis@suffolk.edu

docassemble/GithubFeedbackForm/__init__.py

@@ -1 +1 @@
-__version__ = '0.5.2'
+__version__ = '0.5.3'

docassemble/GithubFeedbackForm/data/questions/feedback.yml

@@ -318,7 +318,7 @@ code: |
   elif is_likely_spam(issue_template.content):
     log("Not saving feedback because it looks like spam")
     mark_task_as_performed('issue noted', persistent=True)
-    issue_url, saved_uuid = None
+    issue_url = saved_uuid = None
     note_issue = False # End block early
   else:
     saved_uuid # Trigger the code to save locally on the server and optionally link the session answers. We do this regardless of whether we send to GitHub

docassemble/GithubFeedbackForm/github_issue.py

@@ -363,23 +363,32 @@ def make_github_issue(
     label: Optional[str] = None,
 ) -> Optional[str]:
     """
-    Create a new Github issue and return the URL.
+    Create a new GitHub issue and return the URL.
 
-    template - the docassemble template for the github issue. Overrides `title` and `body` if provided.
-    title - the title for the github issue
-    body - the body of the github issue
+    Args:
+        template: a docassemble template that overrides `title` and `body`
+        title: the title for the GitHub issue
+        body: the body of the GitHub issue
+        label: optional label to add *if* we can verify or create it
+
+    At least one of template, title, and body is required.
+
+    Returns:
+        str, the URL for the label if it exists, or None if the issue could not be created
     """
     make_issue_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/issues"
-    # Headers
+
+    # Abort early if the configuration or repo owner is invalid
     if not valid_github_issue_config():
         log(
-            "Error creating issue: No valid GitHub token provided. Check your config and see https://github.com/SuffolkLITLab/docassemble-GithubFeedbackForm#getting-started"
+            "Error creating issue: No valid GitHub token provided. "
+            "See https://github.com/SuffolkLITLab/docassemble-GithubFeedbackForm#getting-started"
         )
         return None
-
     if repo_owner.lower() not in _get_allowed_repo_owners():
         log(
-            f"Error creating issue: this form is not permitted to add issues to repositories owned by {repo_owner}. Check your config and see https://github.com/SuffolkLITLab/docassemble-GithubFeedbackForm#getting-started"
+            f"Error creating issue: repositories owned by {repo_owner} are not permitted. "
+            "See https://github.com/SuffolkLITLab/docassemble-GithubFeedbackForm#getting-started"
         )
         return None
 
@@ -388,46 +397,101 @@ def make_github_issue(
         "Accept": "application/vnd.github.v3+json",
     }
 
+    # Abort early for private repos
+    repo_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}"
+    repo_resp = requests.get(repo_url, headers=headers)
+
+    if repo_resp.status_code != 200:
+        log(
+            f"Cannot access repo {repo_owner}/{repo_name}: "
+            f"{repo_resp.status_code} {repo_resp.text}. Maybe it is a private repo?"
+            "Check that the PAT has the correct scopes and that the user can write to the repo."
+        )
+        return None
+
+    # ------------------------------------------------------------------
+    # 1. Figure out whether we can safely apply the label
+    # ------------------------------------------------------------------
+    apply_label = False  # only set to True when we're sure it exists
+
     if label:
-        labels_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/labels"
-        has_label_resp = requests.get(labels_url + "/" + label, headers=headers)
-        if has_label_resp.status_code == 404:
+        make_labels_url = (
+            f"https://api.github.com/repos/{repo_owner}/{repo_name}/labels"
+        )
+        get_labels_url = f"{make_labels_url}/{label}"
+        has_label_resp = requests.get(get_labels_url, headers=headers)
+
+        if has_label_resp.status_code == 200:
+            # Label already exists in the repo
+            apply_label = True
+
+        elif has_label_resp.status_code == 404:
+            # Try to create the label; this may fail if the token lacks permission
             label_data = {
                 "name": label,
                 "description": "Feedback from a Docassemble Interview",
                 "color": "002E60",
             }
             make_label_resp = requests.post(
-                labels_url, data=json.dumps(label_data), headers=headers
+                make_labels_url,
+                data=json.dumps(label_data),
+                headers=headers,
             )
             if make_label_resp.status_code == 201:
-                log("Created the {label} label for the {make_issue_url} repo")
+                log(
+                    f"Created the '{label}' label for the "
+                    f"{repo_owner}/{repo_name} repository"
+                )
+                apply_label = True
             else:
                 log(
-                    f"Was not able to find nor create the {label} label: {make_label_resp.text}"
+                    f"Could not create label '{label}': {make_label_resp.status_code} "
+                    f"{make_label_resp.text}"
                 )
-                label = None
+        else:
+            # 403, 422, etc. → most likely a permissions issue; skip using the label
+            log(
+                f"Unable to verify label '{label}': {has_label_resp.status_code} "
+                f"{has_label_resp.text}"
+            )
 
+    # ------------------------------------------------------------------
+    # 2. Derive title/body from a template, if supplied
+    # ------------------------------------------------------------------
     if template:
-        title = template.subject
-        body = template.content
+        if hasattr(template, "subject"):
+            title = template.subject
+        if hasattr(template, "body"):
+            body = template.content
+
+    if not title and not body:
+        return None
+
+    if not body:
+        body = ""
+
+    if not title:
+        title = "User feedback"
 
+    # Reject obvious spam before calling GitHub
     if is_likely_spam(body):
-        log("Error creating issue: the body of the issue is caught as spam")
+        log("Error creating issue: the body of the issue was classified as spam")
         return None
 
-    # Create our issue
-    data: Dict[str, Union[None, str, List[str]]] = {
+    # ------------------------------------------------------------------
+    # 3. Assemble and POST the issue
+    # ------------------------------------------------------------------
+    data: Dict[str, Union[str, List[str]]] = {
         "title": title,
         "body": body,
     }
-    if label:
+    if apply_label and label is not None:
         data["labels"] = [label]
 
-    # Add the issue to our repository
     response = requests.post(make_issue_url, data=json.dumps(data), headers=headers)
+
     if response.status_code == 201:
         return response.json().get("html_url")
     else:
-        log(f'Could not create Issue "{title}", results {response.text}')
+        log(f'Could not create issue "{title}": {response.status_code} {response.text}')
         return None

setup.py

@@ -43,7 +43,7 @@ def find_package_data(where='.', package='', exclude=standard_exclude, exclude_d
     return out
 
 setup(name='docassemble.GithubFeedbackForm',
-      version='0.5.2',
+      version='0.5.3',
       description=('Integration of GitHub issues with Docassemble interviews for collecting user feedback'),
       long_description='# docassemble.GithubFeedbackForm\r\n\r\nA package that uses the GitHub API to gather feedback and then submit issues to Github that can be embedded\r\ninto a Docassemble interview. Makes it easy to collect per-page feedback.\r\n\r\nThis package is designed to support the following workflow:\r\n\r\n1. Work is stored on a public GitHub repository, or at least, you setup a repository to collect feedback.\r\n1. There is one package per "interview"/"app".\r\n2. Each question block has a unique question ID.\r\n3. Preferably--questions are triggered in an interview order block. If you use a series of `mandatory`\r\n  blocks instead of a single mandatory block, the `variable` listed in the bug report may not be as useful.\r\n\r\n## Getting started\r\n\r\n1. Create a new GitHub user and create a personal access token on it. The personal access\r\n   token needs minimal permissions. Specifically, it needs to be allowed to make pull requests.\r\n   Pull request access is allowed for anyone by default when you create a new, public GitHub repository.\r\n3. Edit your config, and create a block like this:\r\n\r\n```yaml\r\ngithub issues:\r\n  username: "YOUR_NEW_DEDICATED_ISSUE_CREATION_ACCOUNT"\r\n  token: "..." # A valid GitHub personal access token associated with the username above\r\n  default repository owner: YOUR_GITHUB_USER_OR_ORG_HERE\r\n  allowed repository owners: # List the repo that your account will be allowed to create issues on\r\n    - YOUR_GITHUB_USER_OR_ORG_HERE \r\n    - SECOND_GITHUB_USER_OR_ORG\r\n```\r\n\r\n  Note that it is important to provide a list of allowed repository owners.\r\n  This is used to prevent your form from being used to spam GitHub \r\n  repositories with feedback.\r\n  \r\n3. Add a link on each page, in the footer or `under` area.  \r\n   You can use the `feedback_link()` function to add a link, like this:\r\n   `[:comment-dots: Feedback](${ feedback_link(user_info()) } ){:target="_blank"}`\r\n   \r\n   Optional parameters:\r\n    - `i`: the feedback form, like: docassemble.AssemblyLine:feedback.yml\r\n    - `github_repo`: repo name, like: docassemble-AssemblyLine\r\n    - `github_user`: owner of the repo, like: suffolklitlab\r\n    - `variable`: variable being sought, like: intro\r\n    - `question_id`:  id of the current question, like: intro\r\n    - `package_version`: version number of the current package\r\n    - `filename`: filename of the interview the user is providing feedback on.\r\n    \r\n    Each has a sensible default. Most likely, you will limit your custom\r\n    parameters to the `github_repo` if you want feedback links to work\r\n    from the docassemble playground.\r\n    \r\n    You will also need to include the `github_issue.py` module in your parent interview,\r\n    like this: \r\n    ```yaml\r\n    ---\r\n    modules:\r\n      - docassemble.GithubFeedbackForm.github_issue\r\n    ```\r\n    \r\n4. Optionally, create your own feedback.yml file. If you want a custom feedback.yml,\r\n   it should look like this, with whatever customizations you choose:\r\n\r\n```yaml\r\ninclude:\r\n  - docassemble.GithubFeedbackForm:feedback.yml\r\n---\r\ncode: |\r\n  al_feedback_form_title = "Your title here"  \r\n---\r\ncode: |\r\n  # This email will be used ONLY if there is no valid GitHub config\r\n  al_error_email = "your_email@yourdomain.com"\r\n---\r\ntemplate: al_how_to_get_legal_help\r\ncontent: |\r\n  If you need more help, these are free resources:\r\n\r\n  ... [INCLUDE STATE-SPECIFIC RESOURCES]      \r\n```\r\n\r\nYou may also want to customize the metadata: title, exit url and override \r\nany specific questions, add a logo, etc.    \r\n\r\n## Author\r\n\r\nQuinten Steenhuis, qsteenhuis@suffolk.edu\r\n',
       long_description_content_type='text/markdown',