git-bot-feedback

A Python library (written in Rust) designed for CI tools to easily submit feedback on a git server.

Feedback on a git server using this library can be in the form of

• thread comments (for a PR or commit)

• setting output variables for other CI tools to consume

• append a summary comment to a CI workflow run’s summary page

• mark the start and end of a group of log statements (in the CI workflow run’s logs)

• files annotations

• Pull Request reviews

• get a list of changed files in a PR or commit (including line numbers shown in the diff)

This uses async functions to access network resources. Thus, an asyncio event loop is required.

Supported git servers

This project is designed to easily add support for various git servers. The following is just a list of git servers that are planned (in order or priority).

• GitHub

• GitLab

  GitLab support requires GitLab v17.9 or newer and a GITLAB_TOKEN environment variable (an access token). See GitLab token permissions for the permissions each feature needs. GitLab does not support

  • posting thread comments for commits (push events)

  • output variables and step summaries (output variables are only logged)

  • hiding outdated PR review summary comments

• Gitea

  Gitea does not support

  • posting thread comments for commits (push events)

  • programmatically deleting a PR reviews’ individual comments, rather we can only resolve them (currently). However, deleting an entire PR review is supported.

  Only a repository admin can dismiss a PR review. If the token’s user is not an admin, outdated reviews can only be deleted (see ReviewOptions.delete_review_comments).

• Forgejo

  Forgejo uses the Gitea implementation, so the same limitations apply. Forgejo support requires Forgejo Runner v7.0.0 or newer, which sets the FORGEJO_ACTIONS environment variable. The token is read from the GITEA_TOKEN environment variable, or the FORGEJO_TOKEN environment variable that the runner sets automatically. Forgejo also does not support resolving a PR review’s individual comments.

• BitBucket

Currently, only GitHub, GitLab, Gitea, and Forgejo are supported.

LGPL license

This project is licensed under LGPL-3.0-or-later.

Since this library ultimately requires write access to users’ projects (to allow posting comments), it could easily be modified with malicious intent.

By using the LGPL-3.0-or-later license, we can offer some assurance and help safeguard end-users’ data/privacy because the following conditions must be met:

• the source code is publicly available

• any redistributed forms must state their modifications (if any)

• API
  • Git Client
    • GitClient
      • GitClient.api_url
      • GitClient.append_step_summary()
      • GitClient.client_kind
      • GitClient.cull_pr_reviews()
      • GitClient.end_log_group()
      • GitClient.event_name
      • GitClient.get_list_of_changed_files()
      • GitClient.is_debug_enabled()
      • GitClient.is_pr_event()
      • GitClient.is_pr_same_remote()
      • GitClient.post_pr_review()
      • GitClient.post_thread_comment()
      • GitClient.send_api_request()
      • GitClient.set_user_agent()
      • GitClient.start_log_group()
      • GitClient.token_env_vars
      • GitClient.try_next_page()
      • GitClient.workspace_root()
      • GitClient.write_file_annotations()
      • GitClient.write_output_variables()
    • nearest_git_root()
  • HTTP Requests
    • Request
      • Request.body
      • Request.headers
      • Request.method
      • Request.set_token()
      • Request.url
    • Response
      • Response.body
      • Response.headers
      • Response.status
  • Errors
    • GitBotFeedbackError
    • RequestError
    • RateLimitError
    • ParseError
    • EnvironmentError
  • Thread Comments
    • ThreadCommentOptions
      • ThreadCommentOptions.comment
      • ThreadCommentOptions.kind
      • ThreadCommentOptions.marker
      • ThreadCommentOptions.no_lgtm
      • ThreadCommentOptions.policy
    • CommentKind
      • CommentKind.Lgtm
      • CommentKind.Concerns
    • CommentPolicy
      • CommentPolicy.Anew
      • CommentPolicy.Update
  • Pull Request Reviews
    • ReviewOptions
      • ReviewOptions.action
      • ReviewOptions.allow_closed
      • ReviewOptions.allow_draft
      • ReviewOptions.comments
      • ReviewOptions.delete_review_comments
      • ReviewOptions.marker
      • ReviewOptions.summary
    • ReviewAction
      • ReviewAction.Approve
      • ReviewAction.RequestChanges
      • ReviewAction.Comment
    • ReviewComment
      • ReviewComment.comment
      • ReviewComment.line_end
      • ReviewComment.line_start
      • ReviewComment.path
  • File Annotations
    • FileAnnotation
      • FileAnnotation.end_column
      • FileAnnotation.end_line
      • FileAnnotation.message
      • FileAnnotation.path
      • FileAnnotation.severity
      • FileAnnotation.start_column
      • FileAnnotation.start_line
      • FileAnnotation.title
    • AnnotationLevel
      • AnnotationLevel.Debug
      • AnnotationLevel.Notice
      • AnnotationLevel.Warning
      • AnnotationLevel.Error
  • Output Variables
    • OutputVariable
      • OutputVariable.name
      • OutputVariable.validate_py()
      • OutputVariable.value
  • File Changes
    • FileFilter
      • FileFilter.extensions
      • FileFilter.ignored
      • FileFilter.is_file_ignored()
      • FileFilter.is_file_in_list()
      • FileFilter.is_file_not_ignored()
      • FileFilter.is_qualified()
      • FileFilter.not_ignored
      • FileFilter.parse_submodules()
      • FileFilter.walk_dir()
    • DiffHunkHeader
      • DiffHunkHeader.new_lines
      • DiffHunkHeader.new_start
      • DiffHunkHeader.old_lines
      • DiffHunkHeader.old_start
    • FileDiffLines
      • FileDiffLines.added_lines
      • FileDiffLines.added_ranges
      • FileDiffLines.diff_hunks
      • FileDiffLines.from_info()
      • FileDiffLines.is_hunk_in_diff()
      • FileDiffLines.is_line_in_diff()
    • LinesChangedOnly
      • LinesChangedOnly.git_bot_feedback.LinesChangedOnly.On
      • LinesChangedOnly.git_bot_feedback.LinesChangedOnly.Off
      • LinesChangedOnly.git_bot_feedback.LinesChangedOnly.Diff
    • parse_diff()