hub4j/github-api

If a user has 2FA enabled and the client attempts an operation that requires authentication, the GitHub API may return a 401 Unauthorized status with an X-GitHub-OTP header.

When this happens, the GitHubClient detects the requirement and throws a GHOTPRequiredException. This exception contains the response header fields, allowing you to identify that an OTP is needed to proceed.

The GitHubRateLimitChecker acts as a guard before making API requests. It works by:

1. Selecting the Target: It identifies the correct RateLimitChecker based on the RateLimitTarget of the upcoming request.
2. Evaluating Quota: It retrieves the current rate limit information from the GitHubClient.
3. Looping and Waiting: If the RateLimitChecker determines that the limit has been exceeded (via checkRateLimit), the checker will:
   • Sleep for the duration specified by the checker.
   • Sleep for an additional 1-second buffer to account for clock drift/reset timing.
   • Refresh the rate limit information from the server.
   • Repeat the check until the RateLimitChecker returns false (indicating it is safe to proceed).

This looping mechanism allows for complex strategies, such as polling the server for a new quota after a wait period.

By default, the commit list returned by GHCompare is limited to 250 results. To handle comparisons involving more than 250 commits, you must enable pagination on the GHRepository instance before performing the comparison.

To use pagination:

1. Call GHRepository#setCompareUsePaginatedCommits(true).
2. Call GHRepository#getCompare(base, head).
3. Use GHCompare#listCommits() to get a PagedIterable<Commit>, which allows you to iterate through all commits progressively using GitHub's paginated API.

Use GHDiscussionBuilder to programmatically create a new GitHub discussion or update an existing one. The builder follows a fluent API pattern where you set properties like title and body and then call done() to commit the changes.

Note that the builder is generic (GHDiscussionBuilder<S>). Depending on the implementation context, calling methods like title() or body() returns either the builder itself for chaining or an updated GHDiscussion instance. To finalize the operation and receive the resulting GHDiscussion object, you must call .done().

You can retrieve individual header values using the header(String name) method. This method returns the first value associated with the provided header name, or null if the header is missing.

To retrieve all values associated with a specific header field, use headers(String field), which returns a List<String>.

The GitHubClient is the core engine for communicating with the GitHub API. It is thread-safe and can be used to send multiple requests simultaneously. You can send requests by providing a GitHubRequest object or a GitHubRequest.Builder.

To process the response body, you must provide a BodyHandler. If no handler is provided, the response body will be null. The client automatically handles retries for connection errors and certain API-level errors (like rate limits or expired tokens) based on internal logic.

The GHLabelBuilder is used to configure the properties of a GitHub label. You can set the name, color, and description of a label. This builder follows a fluent API pattern where each method call returns an intermediate type S (often the builder itself or the GHLabel instance) to allow chaining.

Note: Methods in this builder are marked as @BetaApi and may change in future versions.

You can retrieve the current rate limit status from the server using getRateLimit(). This returns a GHRateLimit object containing information such as the limit, remaining requests, and the reset time.

Note: For some GitHub Enterprise versions where the /rate_limit endpoint might return a 404, the client will return the most recent rate limit information observed from response headers of previous requests.