ADR 0002-git-server-integration

Context¶

The command line tool review-assist (ra)'s current main purpose is to provide an automated review of git change requests from git servers. I want to support multiple types of git change requests.

• GitLab merge requests (MR)
• ForgeJo pull requests (PR)

Decision¶

Both Gitlab and Forgejo have a REST API with good documentation. By using it in our tool to interact with the git server, the client code can share the same dependency (an HTTP client) and flow.

I will devise a python protocol to abstract the git server interaction into shared behaviours. Then an adapter class can be created implementing the git server protocol. By using a dedicated adapter client class per git server, we are leaving the door open to leverage functionalities specific to a given git server.

That design will also still be viable if we want to mix in adapter that usees other modalities.

Implementation¶

Python protocols provide a clean approach to specify a common set of behaviours I want all inference adapters to implement, without the strictness and limitation of class hierarchy or the boilerplate of full-on plugin systems.

classDiagram
    direction LR

    class GitServerProtocol {
        <<protocol>>
        +get_from_server(project_id, needs_auth, api_path, query_string, expect_json)
        +post_to_server(project_id, api_path, data)
        +check_health() : bool
    }

    class GitlabClientAdapter {
        -base_url: str
        -private_token: SensitiveConfigValue
        -client: httpx.Client
        +GitlabClientAdapter(base_url, private_token)
        +check_health() : bool
        +get_from_server(...) : Any
        +post_to_server(project_id, api_path, data) : Any
    }

    class ForgejoClientAdapter {
        -base_url: str
        -private_token: SensitiveConfigValue
        -client: httpx.Client
        +GitlabClientAdapter(base_url, private_token)
        +check_health() : bool
        +get_from_server(...) : Any
        +post_to_server(project_id, api_path, data) : Any
    }

    GitlabClientAdapter --|> GitServerProtocol : implements
    ForgejoClientAdapter --|> GitServerProtocol : implements

Alternatives considered¶

1. Use CLI tools glab and fj to interact with the git servers.
2. use git native commands to interact with the git servers.
3. Have a generic REST client library to interact with all the git servers.

Tradeoffs with using CLI tools¶

+ No need to manage private tokens
+ Leverage existing official tool from git server vendors
+ No need to keep up with API changes
- Greater uncertainty about the runtime environment
- Relies on the user to install, configure and update the tool
- Workflow differences make composability with this tool difficult

Tradeoffs with using git native commands¶

+ No need to manage private tokens
+ No need to keep up with API changes
+ The tooling is already installed on the user's machine
- No online discussions possible around the generated review
- No access to high level workflow features of the git servers (like assignments, approvals, labels)

The main purpose of the code review is to generate discussions amongst developers that will result in: * Maintained or increased quality of the product being developed * Knowledge sharing amongst the team (bus factor, continuous learning)

Using git native commands will not allow us to do that (more work will be necessary to build the forum-like web-based review publishing), while relying on git server's collaboration features accessible through their API will.

Tradeoffs with using a generic client library¶

+ Simple architecture
- Code complexity increases as we add support for more git servers
- Code complexity increases when we want to leverage specific features of the git servers
- It assumes the interface to git servers will always be a REST API

Since one of the core tenets of this tool is to support multiple git servers, and I intend to leverage any feature that improves the quality of published reviews, this approach is not viable.

Consequences¶

Gains¶

I can independently develop and maintain the code for each git server adapter, with the ability to leverage or not the git server's collaboration features thanks to API access. The adapter implementing a common python protocol guarantees that a baseline of features will be available to all git server adapters and the behaviours will be consistent.

Need to be managed¶

• Network flakiness
• Access control to the git servers

The user will bring its own private tokens in the configuration or as environment variable. Alternatively, the tool will prompt the user to enter the private token if none of the above is used.

Extensive exception handling will be implemented to handle network errors, and the tool will also implement a retry mechanism to handle transient errors.

Drawbacks¶

• API changes in the git servers can happen.

Both REST APIs are versioned and documented, so I can adapt the tool when the API changes, and I have some leeway due to the versioned API.