This project is a Java library for communicating with the GitHub API. The goal of the library is to support 100% of the GitHub v3 API. The library is currently used by the GitHub Mylyn connector for working with GitHub issues, pull requests, gists, and repositories from within Eclipse.
Built versions of the GitHub Java library are currently available from the Sonatype OSS repository. Javadoc and source JARs are available as well from the Sonatype OSS repository.
The library is composed of 3 main packages.
This package contains all the model classes representing the resources available through the API such as repositories, commits, user, teams, and issues. The model classes contains getters and setters for all the properties present in the GitHub API JSON response. The Google Gson library is used serialize and deserialize these objects to/from JSON.
This package contains classes communicate with the GitHub API over HTTPS. The client package is also responsible for converting JSON responses to appropriate Java model classes as well as generating request exceptions based on HTTP status codes.
This package contains the classes that invoke API calls and return model classes representing resources that were created, read, updated, or deleted. Service classes are defined for the resources they interact with such as IssueService, PullRequestService, and RepositoryService.
//Basic authentication GitHubClient client = new GitHubClient(); client.setCredentials("user", "passw0rd");
//OAuth2 token authentication GitHubClient client = new GitHubClient(); client.setOAuth2Token("SlAV32hkKG");
The following example prints the number of watchers for each repository associated with the defunkt user.
RepositoryService service = new RepositoryService(); for (Repository repo : service.getRepositories("defunkt")) System.out.println(repo.getName() + " Watchers: " + repo.getWatchers());
The following example checks if Pull Request #45 is mergeable and if it is then it automatically merges it.
PullRequestService service = new PullRequestService(); service.getClient().setCredentials("user", "passw0rd"); RepositoryId repo = new RepositoryId("rails", "rails"); if (service.getPullRequest(repo, 45).isMergeable()) service.merge(repo, 45, "merging a pull request");
The following examples forks the rails/rails repository into the currently authenticated user's account.
RepositoryService service = new RepositoryService(); service.getClient().setCredentials("user", "passw0rd"); RepositoryId toBeForked = new RepositoryId("rails", "rails"); service.forkRepository(toBeForked);
The following examples creates a Gist that contains a single file.
GistFile file = new GistFile(); file.setContent("System.out.println(\"Hello World\");"); Gist gist = new Gist(); gist.setDescription("Prints a string to standard out"); gist.setFiles(Collections.singletonMap("Hello.java", file)); GistService service = new GistService(); service.getClient().setCredentials("user", "passw0rd"); gist = service.createGist(gist); //returns the created gist
Clients use an address of api.github.com by default but this can be overridden when the client is created for the case where you are using GitHub Enterprise.
GitHubClient client = new GitHubClient("github.mycompany.com"); UserService service = new UserService(client); service.getUser("internaluser");
The GitHub Java API is built using Apache Maven.
Run the following command to build a JAR file containing the GitHub Java API without dependencies:
$ mvn -f pom-jar.xml clean install
The GitHub Java API can also be built as a JAR that includes all the dependencies (Google Gson). This technique uses the Maven Shade Plugin to build an all-in-one JAR file.
$ mvn -f pom-jar.xml clean install -P shade