mirror of
https://github.com/jlengrand/github-api.git
synced 2026-04-23 00:11:21 +00:00
302 lines
10 KiB
HTML
302 lines
10 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<html>
|
|
<head>
|
|
<title>GitHub API for Java – </title>
|
|
<style type="text/css" media="all">
|
|
@import url("./css/maven-base.css");
|
|
@import url("./css/maven-theme.css");
|
|
@import url("./css/1024px.css");
|
|
@import url("./css/site.css");
|
|
</style>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
</head>
|
|
<body>
|
|
<div id="wrap2"><div id="wrap">
|
|
<div id="header">
|
|
<p id="toplinks">Skip to: <a href="#content">Content</a> | <a href="#sidebar">Navigation</a> | <a href="#footer">Footer</a></p>
|
|
|
|
<h1 id="bannerLeft">
|
|
<a href="./">
|
|
|
|
GitHub API for Java
|
|
|
|
</a>
|
|
</h1>
|
|
|
|
<p id="slogan">GitHub API for Java</p>
|
|
</div>
|
|
<div id="breadcrumbs">
|
|
<div class="xright"> </div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="sidebar">
|
|
<div id="navcolumn">
|
|
<h2>
|
|
Git Hub API for Java
|
|
</h2><ul>
|
|
|
|
<li class="none">
|
|
<strong>Introduction</strong>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="https://mvnrepository.com/artifact/org.kohsuke/github-api">Download</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="https://github.com/hub4j/github-api">Source code</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="https://groups.google.com/forum/#!forum/github-api">Mailing List</a>
|
|
</li>
|
|
</ul>
|
|
<h2>
|
|
Guides
|
|
</h2><ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="expanded">
|
|
<a href="githubappflow.html">GitHub App Auth Flow</a>
|
|
<ul>
|
|
|
|
<li class="none">
|
|
<a href="githubappjwtauth.html">JWT Authentication</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="githubappappinsttokenauth.html">App Installation Token</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="createorglevelresources.html">Working with organizations</a>
|
|
</li>
|
|
</ul>
|
|
<h2>
|
|
References
|
|
</h2><ul>
|
|
|
|
<li class="none">
|
|
<a href="apidocs/index.html">Javadoc</a>
|
|
</li>
|
|
</ul>
|
|
<h2>
|
|
Project Documentation
|
|
</h2><ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="expanded">
|
|
<a href="project-info.html">Project Information</a>
|
|
<ul>
|
|
|
|
<li class="none">
|
|
<a href="dependencies.html">Dependencies</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="dependency-info.html">Dependency Information</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="distribution-management.html">Distribution Management</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<strong>About</strong>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="licenses.html">Licenses</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="mailing-lists.html">Mailing Lists</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="plugin-management.html">Plugin Management</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="plugins.html">Plugins</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="scm.html">Source Code Management</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="summary.html">Summary</a>
|
|
</li>
|
|
|
|
<li class="none">
|
|
<a href="team.html">Team</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="collapsed">
|
|
<a href="project-reports.html">Project Reports</a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div id="content">
|
|
<div id="contentBox">
|
|
<section>
|
|
<h2><a name="What_is_this.3F"></a>What is this?</h2>
|
|
<p>This library defines an object oriented representation of the GitHub API. By "object oriented" we mean there are classes that correspond to the domain model of GitHub (such as <code>GHUser</code> and <code>GHRepository</code>), operations that act on them as defined as methods (such as <code>GHUser.follow()</code>), and those object references are used in favor of using string handle (such as <code>GHUser.isMemberOf(GHOrganization)</code> instead of <code>GHUser.isMemberOf(String)</code>)</p>
|
|
<p>The library supports both github.com and GitHub Enterprise.</p>
|
|
<p>Most of the GitHub APIs are covered, although there are some corners that are still not yet implemented.</p></section><section>
|
|
<h2><a name="Sample_Usage"></a>Sample Usage</h2>
|
|
<div class="source">
|
|
<pre>GitHub github = GitHub.connect();
|
|
|
|
GHRepository repo = github.createRepository(
|
|
"new-repository","this is my new repository",
|
|
"https://www.kohsuke.org/",true/*public*/);
|
|
repo.addCollaborators(github.getUser("abayer"),github.getUser("rtyler"));
|
|
repo.delete();</pre></div></section><section>
|
|
<h2><a name="Authentication"></a>Authentication</h2>
|
|
<p>The library allows connecting to GitHub via several different authentication mechanisms.</p><section>
|
|
<h3><a name="Programmatically"></a>Programmatically</h3>
|
|
<p>To connect via Username and Password (not recommended):</p>
|
|
<div class="source">
|
|
<pre>GitHub github = new GitHubBuilder().withPassword("my_user", "my_passwd").build();</pre></div>
|
|
<p>To connect via Personal access token:</p>
|
|
<div class="source">
|
|
<pre>// If you don't specify the GitHub user id then the sdk will retrieve it via /user endpoint
|
|
GitHub github = new GitHubBuilder().withOAuthToken("my_personal_token").build();
|
|
|
|
// If the token has access to an organization, you can specify it here.
|
|
GitHub github = new GitHubBuilder().withOAuthToken("my_personal_token","user_id_OR_org_name").build();</pre></div>
|
|
<p>To connect via JWT token as a GitHub App:</p>
|
|
<div class="source">
|
|
<pre>GitHub github = new GitHubBuilder().withJwtToken("my_jwt_token").build();</pre></div>
|
|
<p>To connect via GitHub App installation token on behalf of a user or organization:</p>
|
|
<div class="source">
|
|
<pre>GitHub github = new GitHubBuilder().withAppInstallationToken("my_installation_token").build();</pre></div></section><section>
|
|
<h3><a name="Property_file"></a>Property file</h3>
|
|
<p>This library defines a common convention so that applications using this library will look at a consistent location. In this convention, the library looks at <code>~/.github</code> property file. The content of the files depends on the way you want this library to authenticate as shown below:</p>
|
|
<p>To connect via Username and Password (not recommended):</p>
|
|
<div class="source">
|
|
<pre>login=kohsuke
|
|
password=012345678</pre></div>
|
|
<p>To connect via Personal access token:</p>
|
|
<div class="source">
|
|
<pre>oauth=4d98173f7c075527cb64878561d1fe70</pre></div>
|
|
<p>To connect via Personal access token as a user or organization:</p>
|
|
<div class="source">
|
|
<pre>login=my_org
|
|
oauth=4d98173f7c075527cb64878561d1fe70</pre></div>
|
|
<p>To connect via JWT token as a GitHub App:</p>
|
|
<div class="source">
|
|
<pre>jwt=my_jwt_token</pre></div>
|
|
<p>Once your <code>~/.github</code> property file is properly configured, you can obtain a <code>GitHub</code> instance using:</p>
|
|
<div class="source">
|
|
<pre>// if you are using the default configuration file
|
|
GitHub github = GitHubBuilder.fromPropertyFile().build();
|
|
|
|
// if you need to use a separate configuration file
|
|
GitHub github = GitHubBuilder.fromPropertyFile("location/my_custom_github.properties").build();</pre></div></section><section>
|
|
<h3><a name="Environmental_variables"></a>Environmental variables</h3>
|
|
<p>This library also allows developers to authenticate GitHub with environmental variables.</p>
|
|
<p>To connect via Username and Password (not recommended):</p>
|
|
<div class="source">
|
|
<pre>export GITHUB_LOGIN=kohsuke
|
|
export GITHUB_PASSWORD=012345678</pre></div>
|
|
<p>To connect via Personal access token:</p>
|
|
<div class="source">
|
|
<pre>export GITHUB_OAUTH=4d98173f7c075527cb64878561d1fe70</pre></div>
|
|
<p>To connect via Personal access token as a user or organization:</p>
|
|
<div class="source">
|
|
<pre>export GITHUB_LOGIN=my_org
|
|
export GITHUB_OAUTH=4d98173f7c075527cb64878561d1fe70</pre></div>
|
|
<p>To connect via JWT token as a GitHub App:</p>
|
|
<div class="source">
|
|
<pre>export GITHUB_JWT=my_jwt_token</pre></div>
|
|
<p>Once exported, you can obtain a <code>GitHub</code> instance using:</p>
|
|
<div class="source">
|
|
<pre>GitHub github = GitHubBuilder.fromEnvironment().build();</pre></div></section></section><section>
|
|
<h2><a name="Pluggable_HTTP_client"></a>Pluggable HTTP client</h2>
|
|
<p>This library comes with a pluggable connector to use different HTTP client implementations through <code>HttpConnector</code>. In particular, this means you can use <a class="externalLink" href="https://square.github.io/okhttp/">OkHttp</a>, so we can make use of it's HTTP response cache. Making a conditional request against the GitHub API and receiving a 304 response <a class="externalLink" href="https://developer.github.com/v3/#conditional-requests">does not count against the rate limit</a>.</p>
|
|
<p>The following code shows an example of how to set up persistent cache on the disk:</p>
|
|
<div class="source">
|
|
<pre>Cache cache = new Cache(cacheDirectory, 10 * 1024 * 1024); // 10MB cache
|
|
GitHub gitHub = GitHubBuilder.fromEnvironment()
|
|
.withConnector(new OkHttpConnector(new OkUrlFactory(new OkHttpClient().setCache(cache))))
|
|
.build();</pre></div></section>
|
|
</div>
|
|
</div>
|
|
<div id="footer">
|
|
<div class="xright">©
|
|
2021
|
|
|
|
<a href="http://kohsuke.org/">Kohsuke Kawaguchi</a> and other contributors
|
|
|
|
|
|
|
|
|
|
|
|
| Last Published: 2021-01-05
|
|
| Version: 1.119
|
|
</div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
</div></div>
|
|
</body>
|
|
</html>
|