Git Client

class git_bot_feedback.GitClient

api_url

The root URL of the git server’s REST API.

Use this to assemble the url of a Request. It is None when not run by a CI platform.

append_step_summary(comment: str) → None

–

Appends a given comment to the CI workflow’s summary page.

This is the least obtrusive and recommended for push events. Not all Git servers natively support this type of feedback. GitHub and Gitea are known to support this. For all other git servers, this is a non-op returning [Ok]

client_kind

The name of git server implementation is being used.

cull_pr_reviews(options: ReviewOptions) → ReviewOptions

–

Resolve outdated PR review comments and remove duplicate/reused comments.

This should be used before [Self::post_pr_review()] to avoid posting duplicates of existing comments. The [ReviewOptions::comments] will be modified to only include comments that should be posted for the current PR review. After calling this function, the [ReviewOptions::summary] can be made to reflect the actual review being posted.

The [ReviewOptions::marker] is used to identify comments from this software. The [ReviewOptions::delete_review_comments] flag will delete outdated review comments. The [ReviewOptions::delete_review_comments] flag does not apply to review summary comments nor threads of discussion within a review. A review summary comment will only be hidden/collapsed when all comments in the corresponding review are resolved.

This function does nothing for non-PR events.

Returns a copy of the given ReviewOptions with duplicate comments removed.

end_log_group(name: str) → None

–

Mark the end of a group of logs statements.

Some CI platforms expect the given name to match an already started group of logs. Other CI platforms do not actually used the given name.

event_name

Get the name of the current CI event.

This will return None if the event name is not known for the CI platform.

get_list_of_changed_files(file_filter: FileFilter, lines_changed_only: LinesChangedOnly, base_diff: str | None = None, ignore_index: bool = False) → dict[str, FileDiffLines]

–

A way to get the list of changed files in the context of the CI event.

This method will parse diff blobs and return a list of changed files.

The default implementation uses git diff to get the list of changed files. So, the default implementation requires git installed and a non-shallow checkout.

Other implementations use the Git server’s REST API to get the list of changed files.

is_debug_enabled()

Is debug mode enabled?

Typically, A CI platform will have a way to enable debug level logs for a job or workflow. This method should be implemented to reflect the supported CI platform’s implementation.

is_pr_event()

Is the current CI event trigger a Pull Request?

This will not check if a push event’s instigating commit is part of any PR.

is_pr_same_remote()

Is the Pull Request event originating from the same remote repository?

Returns false if the event is not a Pull Request event, or if the Pull Request originates from a fork repository.

post_pr_review(options: ReviewOptions) → None

–

Post a PR review based on the given options.

This is expected to be used after calling [Self::cull_pr_reviews()] to avoid posting duplicates of existing comments. Once the duplicates are filtered out, the [ReviewOptions::summary] can be made to reflect the actual review being posted.

This function does nothing for non-PR events.

post_thread_comment(options: ThreadCommentOptions) → None

–

A way to post feedback to the Git server’s GUI.

The given [ThreadCommentOptions::comment] should be compliant with the Git server’s requirements (ie. the comment length is within acceptable limits).

send_api_request(request: Request) → Response

–

Send an HTTP request, respecting the REST API’s rate limits.

The request’s headers override the client’s default headers.

Only same-origin redirects are followed (up to 10), so credential headers like GitLab’s PRIVATE-TOKEN are never forwarded to another origin. A redirect to a different origin is not followed; the 3xx response is returned as is (see its Location header).

In the event where a secondary rate limit is reached, this will wait for the time interval (if specified by the server) and retry afterward. Raises RateLimitError or RequestError on failure. This can also throw ValueError if the request’s URL, method, or headers values are invalid.

set_user_agent(user_agent)

Set the user agent for the underlying HTTP request client.

By default the user agent is set to this lib’s name and version. See [USER_AGENT] for the default value.

start_log_group(name: str) → None

–

Mark the start of a group of logs statements.

The name given is used as the unique group name.

token_env_vars

The names of the environment variables that may hold the REST API’s authentication token, in order of precedence.

It is empty when not run by a CI platform.

try_next_page(headers: dict[str, str]) → str | None

–

Gets the URL for the next page from the headers in a paginated response.

Returns None if the current response is the last page.

workspace_root()

The root folder of the workspace, as named by the CI platform’s environment (for example, GITHUB_WORKSPACE on GitHub).

Returns None when not run by a CI platform. Raises a EnvironmentError if the CI platform’s environment variable cannot be read. This does not fall back to the working directory or nearest_git_root().

write_file_annotations(annotations: list[FileAnnotation]) → None

–

Sets the given annotations as file annotations.

Not all Git servers support this on their free tiers, namely GitLab.

write_output_variables(vars: list[OutputVariable]) → None

–

Sets the given vars as output variables.

These variables are designed to be consumed by other steps in the CI workflow.

git_bot_feedback.nearest_git_root(path: str | Path | os.PathLike[str]) → Path | None

–

Find the closest folder, starting with path itself, that has a .git folder or file (as in a git submodule).

A relative path is resolved against the working directory. The returned path is absolute, but symbolic links are not resolved. Returns None if no such folder is found. This does not invoke the git CLI.