Skip to content

About

Java 21 SDK for the GitHub REST API: immutable objects with methods, like issue.close() and pullRequest.merge(). Unofficial.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

10 Commits

Folders and files

Repository files navigation

github-sdk

Java 21 object layer over github-rest-client: objects that carry methods which call the GitHub REST API, such as repo.createIssue(...) and issue.close().

Maven Central Java 21 License: MIT Build Codacy Coverage Codacy Badge

Why this library

  • Objects instead of coordinates. An issue knows its repository, so issue.comment("Thanks") needs no owner, name or number.
  • What GitHub holds, not a copy. Every operation returns a new object built from GitHub's answer. Objects are immutable, and refresh() reloads one.
  • No hidden requests. A Repository from sdk.repository("octocat", "Hello-World") is a handle and makes no request until you call fetch(). Every other object is loaded, and every network call is a visible method call.
  • The client stays within reach. Every object has response(), the complete github-rest-client response, and you keep the GitHub client you passed in for everything the objects do not cover.
  • Small on purpose. Synchronous REST only: no async API, and GraphQL is a separate library, github-graphql-client.

Comparison with hub4j/github-api

hub4j/github-api is the long-established Java library for GitHub and a fine choice. It has the same object-oriented style as this SDK, with classes such as GHRepository and GHUser that carry the operations. The differences are in the foundation. The hub4j column is taken from its documentation as of November 2026.

github-sdk hub4j/github-api
Style Objects with methods, on top of a typed client generated from GitHub's OpenAPI descriptions Objects with methods
Objects Immutable; an operation returns a new object built from GitHub's answer, and response() gives the full typed record Its own model classes
Escape hatch The github-rest-client is underneath, so any operation without an object is one call away Its own API
Java 21 11
Maturity New. Smoke-tested live, not yet proven in production; see the Disclaimer Long-established and widely used

Choose hub4j/github-api if you need Java 11 or a library with a long track record. Choose this SDK if you want immutable objects over a client that follows GitHub's own descriptions, with the full typed response always within reach.

Install

Requirements: Java 21. The library is a Java module, io.github.piotr_janczukowicz.githubsdk, and also works on the class path. It depends on github-rest-client, which Maven brings in.

<dependency>
    <groupId>io.github.piotr-janczukowicz</groupId>
    <artifactId>github-sdk</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Replace LATEST_VERSION with the newest entry on the releases page. The versions follow the OpenAPI version of github-rest-client (2026.3.10.N). The library is new and not yet proven in production; see the Disclaimer.

Quick start

GitHubSdk wraps a GitHub client from github-rest-client, so authentication, the GitHub product (github.com, Enterprise Cloud or Enterprise Server) and limits are configured on the client as usual. The SDK has no configuration of its own.

try (GitHubClient client = GitHubClients.create(AuthenticationProviders.bearer(System.getenv("GITHUB_TOKEN")), "my-app/1.0")) {
    GitHubSdk sdk = GitHubSdk.of(client);

    Repository repository = sdk.repository("octocat", "Hello-World");
    Issue issue = repository.createIssue("Found a bug");
    issue.comment("Looking into it");
    Issue closed = issue.close();                       // GitHub's answer, not a local copy

    repository.issues().limit(10).forEach(listed -> System.out.println(listed.number() + " " + listed.title()));
}

The try block only keeps the example short and closes the client at its end. In an application, create the client once and close it once, when the application stops (see Good practices).

What you can do

Each area below is an object you reach from sdk, a Repository, an Organization or a User. The full list of objects and methods names every call.

Area What it covers
Repositories create, update, archive, transfer, fork, star and watch; topics and languages; collaborators and invitations; webhooks and deploy keys; Pages
Code branches and branch protection, rulesets, commits, comparisons, files, multi-file commits, refs, tags, releases and their assets, annotated tags, README
Issues and pull requests issues, comments, labels, milestones, reactions, events, sub-issues and dependencies; pull requests, reviews, review comments, merging
Actions and CI workflows, runs, jobs, artifacts, variables, caches, self-hosted runners, check runs, commit statuses, deployments and environments
Security Dependabot, secret scanning and code scanning alerts, code quality, security advisories, dependency graph and SBOM, interaction limits
People and organizations users, the signed-in account, organizations, teams, members and invitations, SSH, GPG and signing keys, notifications, gists
Projects and packages Projects v2 (read and edit items and fields), GitHub Packages
Platform search, rate limit, events, GitHub Apps and Marketplace, licenses, Markdown rendering

Not covered: Copilot, codespaces, billing, Enterprise Server administration and everything that needs GraphQL, such as discussions. Use github-rest-client for the REST ones. Which areas ran against the real GitHub API is listed in Live smoke tests.

When the SDK does not cover a call

The SDK covers the common work, not every endpoint. For the rest, use github-rest-client directly: the GitHub client behind the SDK is yours, so there is no second client, no second credential and no second configuration. Create the GitHub object yourself, hand it to GitHubSdk.of(...), and keep it for the calls that have no SDK object. Both use the same authentication, retries, cache and rate-limit handling.

try (GitHubClient client = GitHubClients.create(AuthenticationProviders.bearer(System.getenv("GITHUB_TOKEN")), "my-app/1.0")) {
    GitHub github = new GitHub(GitHubCaller.of(client));
    GitHubSdk sdk = GitHubSdk.of(github);

    Repository repository = sdk.repository("octocat", "Hello-World");
    repository.createIssue("Found a bug");                                  // an SDK object

    // no SDK object for this call yet: use the client with the same coordinates
    GitHubRepositoryHashAlgorithmResponse hash =
            github.repositories().repository().getHashAlgorithm(repository.owner(), repository.name());
}

The client names its resources as github.<area>().<group>().<method>(...), and the Javadoc of each method names the HTTP request it sends; see the github-rest-client documentation. What the SDK returns links back to it as well: every object has response(), the complete client record, which you can pass to the client again. What the SDK covers lists every object, so you can check first.

Conventions

All objects behave the same way, so you learn them once:

  • Objects are immutable. An operation returns a new object; the old one keeps its old state.
  • A lookup (repository.issue(42), sdk.user("octocat")) returns an Optional, empty when GitHub answers 404.
  • A list is a lazy, single-use Stream. Pages are fetched as you consume it, so limit(...) stops further requests; a transport failure during iteration is an UncheckedIOException.
  • Several fields at once go through update(): issue.update().title("New").labels(List.of("bug")).send() sends one request with only the fields you set. send() with nothing set throws IllegalStateException.
  • State changes that are not fields are methods on the object: close(), reopen(), merge(...), lock().
  • refresh() reloads an object and throws IllegalStateException when it is gone.
  • Where GitHub's list returns a smaller record than a single lookup (pull requests, branches, teams, search hits for issues and users), the SDK loads each item with one more request as the stream reaches it. The Javadoc says so, and limit(...) bounds the cost. An item that is gone before it is loaded is skipped.
  • A field that GitHub may leave out is an Optional (issue.milestone(), issue.author()).
  • IOException and the client's GitHubApiException pass through unchanged.

Good practices

Conventions says what the SDK does. This is what to do with it.

  • Create the client once and close it once. One client per credential, with one GitHubSdk on top: the client owns the transport and the rate-limit state, so share it for the life of the application, and do not open a client per call. Close it when the application stops. The SDK never closes a client you passed in.
  • Keep the object an operation returns. The object you called it on is not updated; use the result, and call refresh() only when something else may have changed the object.
  • Use handles, load when you need data. sdk.repository(owner, name) costs nothing; call fetch() only for fields the handle does not hold.
  • Always bound a list you read from a large repository. Add limit(...) or stop the stream early, and avoid toList() on a list that can grow, especially one that loads an item per request.
  • Prefer one request over many. update(), protect(), newRuleset(...) and commitTo(branch) collect changes and send them together, instead of one call per field or per file.
  • Decide what an empty lookup means. Handle the Optional instead of calling orElseThrow() by habit, and catch GitHubApiException (not found, forbidden, rate limit) at the place where you can act on it.
  • Configure the client, not the SDK. Retry, backoff, the cache and page size are client settings; see Configure the client.
  • Give the token what the call needs. Prefer a fine-grained token with the permissions of the areas you use. Some areas need more: notifications and packages need a classic token, and creating check runs, installations and Marketplace calls need a GitHub App.
  • Keep secrets out of logs. response() of a secret scanning alert, the payload URL of a webhook, runner tokens and the signed links of artifacts and logs can carry credentials; the Javadoc of each says so.
  • Try an integration on a throwaway repository first. The live smoke tests show how.

Configure the client

Authentication, retries, caching, page size and the GitHub product (github.com, Enterprise Cloud or Enterprise Server) are the client's job, not the SDK's: every object calls the client you pass to GitHubSdk.of(...) (a GitHubClient, a GitHubCaller or a GitHub), so one configuration covers all of them. The SDK has no configuration of its own, and a call made through an object behaves exactly like the same call on the client.

GitHubClientConfiguration configuration = GitHubClientConfiguration.builder()
        .retry(RetryConfiguration.builder().maxRateLimitAttempts(5).build())
        .conditionalCacheMaxEntries(500)
        .pagination(PaginationConfiguration.builder().perPage(100).maxPages(5).build())
        .build();

try (GitHubClient client = GitHubClients.create(
        AuthenticationProviders.bearer(System.getenv("GITHUB_TOKEN")), "my-app/1.0", configuration)) {
    GitHubSdk sdk = GitHubSdk.of(client);
    // use the sdk as usual
}

The options are described in the github-client and github-rest-client documentation:

Packages

The entry points (GitHubSdk, Repository, User, Organization, Team, Search, RateLimit) are in io.github.piotr_janczukowicz.github.sdk. The other objects are grouped by area in sub-packages such as issues, pulls, content, git, actions, security, rulesets, projects and packages.

The internal package is not exported by the module and is not part of the API. The module system hides it only on the module path; on the classpath it is a convention and not a security boundary.

Disclaimer

The SDK is a thin layer over github-rest-client, which is built on the OpenAPI JSON schemas that GitHub publishes in github/rest-api-description; the caveats of that project apply here too.

Only smoke tests have been run on the live GitHub environment, covering particular feature sets. Not every operation has been tested. This library is new and not yet proven in production. Verify the behavior of anything you depend on before using it in production.

About

Java 21 SDK for the GitHub REST API: immutable objects with methods, like issue.close() and pullRequest.merge(). Unofficial.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages