org.kohsuke.github

Class GitHub

java.lang.Object

org.kohsuke.github.GitHub

public class GitHub
extends java.lang.Object

Root of the GitHub API.

Thread safety

This library aims to be safe for use by multiple threads concurrently, although the library itself makes no attempt to control/serialize potentially conflicting operations to GitHub, such as updating & deleting a repository at the same time.

Author:

Kohsuke Kawaguchi

Method Summary

Modifier and Type	Method and Description
void	checkApiUrlValidity() Tests the connection.
static GitHub	connect() Obtains the credential from "~/.github" or from the System Environment Properties.
static GitHub	connect(java.lang.String login, java.lang.String oauthAccessToken)
static GitHub	connect(java.lang.String login, java.lang.String oauthAccessToken, java.lang.String password) Deprecated. Either OAuth token or password is sufficient, so there's no point in passing both. Use connectUsingPassword(String, String) or connectUsingOAuth(String).
static GitHub	connectAnonymously() Connects to GitHub anonymously.
static GitHub	connectToEnterprise(java.lang.String apiUrl, java.lang.String oauthAccessToken) Version that connects to GitHub Enterprise.
static GitHub	connectToEnterprise(java.lang.String apiUrl, java.lang.String login, java.lang.String password)
static GitHub	connectToEnterpriseAnonymously(java.lang.String apiUrl) Connects to GitHub Enterprise anonymously.
static GitHub	connectUsingOAuth(java.lang.String oauthAccessToken)
static GitHub	connectUsingOAuth(java.lang.String githubServer, java.lang.String oauthAccessToken)
static GitHub	connectUsingPassword(java.lang.String login, java.lang.String password)
GHGistBuilder	createGist()
GHCreateRepositoryBuilder	createRepository(java.lang.String name) Starts a builder that creates a new repository.
GHRepository	createRepository(java.lang.String name, java.lang.String description, java.lang.String homepage, boolean isPublic) Deprecated. Use createRepository(String) that uses a builder pattern to let you control every aspect.
GHAuthorization	createToken(java.util.Collection<java.lang.String> scope, java.lang.String note, java.lang.String noteUrl) Creates a new authorization.
HttpConnector	getConnector()
java.util.List<GHEventInfo>	getEvents() Public events visible to you.
GHGist	getGist(java.lang.String id) Gets a sigle gist by ID.
GHLicense	getLicense(java.lang.String key) Deprecated.
java.util.Map<java.lang.String,GHOrganization>	getMyOrganizations() /** This method returns a shallowly populated organizations.
GHMyself	getMyself() Gets the GHUser that represents yourself.
java.util.Map<java.lang.String,java.util.Set<GHTeam>>	getMyTeams() Gets complete map of organizations/teams that current user belongs to.
GHOrganization	getOrganization(java.lang.String name)
GHRateLimit	getRateLimit() Gets the current rate limit.
GHRepository	getRepository(java.lang.String name) Gets the repository object from 'user/reponame' string that GitHub calls as "repository name"
protected GHUser	getUser(GHUser orig) Interns the given GHUser.
GHUser	getUser(java.lang.String login) Obtains the object that represents the named user.
boolean	isAnonymous() Is this an anonymous connection
boolean	isCredentialValid() Ensures that the credential is valid.
PagedIterable<GHRepository>	listAllPublicRepositories() This provides a dump of every public repository, in the order that they were created.
PagedIterable<GHRepository>	listAllPublicRepositories(java.lang.String since) This provides a dump of every public repository, in the order that they were created.
PagedIterable<GHLicense>	listLicenses() Deprecated.
GHNotificationStream	listNotifications() List all the notifications.
<T extends GHEventPayload> T	parseEventPayload(java.io.Reader r, java.lang.Class<T> type) Parses the GitHub event object.
void	refreshCache() clears all cached data in order for external changes (modifications and del
java.io.Reader	renderMarkdown(java.lang.String text) Render a Markdown document in raw mode.
GHContentSearchBuilder	searchContent() Search content.
GHIssueSearchBuilder	searchIssues() Search issues.
GHRepositorySearchBuilder	searchRepositories() Search repositories.
GHUserSearchBuilder	searchUsers() Search users.
void	setConnector(HttpConnector connector) Sets the custom connector used to make requests to GitHub.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

connect

public static GitHub connect()
                      throws java.io.IOException

Obtains the credential from "~/.github" or from the System Environment Properties.

Throws:

java.io.IOException

connectToEnterprise

public static GitHub connectToEnterprise(java.lang.String apiUrl,
                                         java.lang.String oauthAccessToken)
                                  throws java.io.IOException

Version that connects to GitHub Enterprise.

Parameters:

apiUrl - The URL of GitHub (or GitHub enterprise) API endpoint, such as "https://api.github.com" or "http://ghe.acme.com/api/v3". Note that GitHub Enterprise has /api/v3 in the URL. For historical reasons, this parameter still accepts the bare domain name, but that's considered deprecated.

Throws:

java.io.IOException

connectToEnterprise

public static GitHub connectToEnterprise(java.lang.String apiUrl,
                                         java.lang.String login,
                                         java.lang.String password)
                                  throws java.io.IOException

Throws:

java.io.IOException

connect

public static GitHub connect(java.lang.String login,
                             java.lang.String oauthAccessToken)
                      throws java.io.IOException

Throws:

java.io.IOException

connect

public static GitHub connect(java.lang.String login,
                             java.lang.String oauthAccessToken,
                             java.lang.String password)
                      throws java.io.IOException

Deprecated. Either OAuth token or password is sufficient, so there's no point in passing both. Use connectUsingPassword(String, String) or connectUsingOAuth(String).

Throws:

java.io.IOException

connectUsingPassword

public static GitHub connectUsingPassword(java.lang.String login,
                                          java.lang.String password)
                                   throws java.io.IOException

Throws:

java.io.IOException

connectUsingOAuth

public static GitHub connectUsingOAuth(java.lang.String oauthAccessToken)
                                throws java.io.IOException

Throws:

java.io.IOException

connectUsingOAuth

public static GitHub connectUsingOAuth(java.lang.String githubServer,
                                       java.lang.String oauthAccessToken)
                                throws java.io.IOException

Throws:

java.io.IOException

connectAnonymously

public static GitHub connectAnonymously()
                                 throws java.io.IOException

Connects to GitHub anonymously. All operations that requires authentication will fail.

Throws:

java.io.IOException

connectToEnterpriseAnonymously

public static GitHub connectToEnterpriseAnonymously(java.lang.String apiUrl)
                                             throws java.io.IOException

Connects to GitHub Enterprise anonymously. All operations that requires authentication will fail.

Throws:

java.io.IOException

isAnonymous

public boolean isAnonymous()

Is this an anonymous connection

Returns:

true if operations that require authentication will fail.

getConnector

public HttpConnector getConnector()

setConnector

public void setConnector(HttpConnector connector)

Sets the custom connector used to make requests to GitHub.

getRateLimit

public GHRateLimit getRateLimit()
                         throws java.io.IOException

Gets the current rate limit.

Throws:

java.io.IOException

getMyself

@WithBridgeMethods(value=GHUser.class)
public GHMyself getMyself()
                                                          throws java.io.IOException

Gets the GHUser that represents yourself.

Throws:

java.io.IOException

getUser

public GHUser getUser(java.lang.String login)
               throws java.io.IOException

Obtains the object that represents the named user.

Throws:

java.io.IOException

refreshCache

public void refreshCache()

clears all cached data in order for external changes (modifications and del

getUser

protected GHUser getUser(GHUser orig)
                  throws java.io.IOException

Interns the given GHUser.

Throws:

java.io.IOException

getOrganization

public GHOrganization getOrganization(java.lang.String name)
                               throws java.io.IOException

Throws:

java.io.IOException

getRepository

public GHRepository getRepository(java.lang.String name)
                           throws java.io.IOException

Gets the repository object from 'user/reponame' string that GitHub calls as "repository name"

Throws:

java.io.IOException

See Also:

GHRepository.getName()

listLicenses

@Preview
 @Deprecated
public PagedIterable<GHLicense> listLicenses()
                                                            throws java.io.IOException

Deprecated.

Returns a list of popular open source licenses WARNING: This uses a PREVIEW API.

Returns:

a list of popular open source licenses

Throws:

java.io.IOException

See Also:

GitHub API - Licenses

getLicense

@Preview
 @Deprecated
public GHLicense getLicense(java.lang.String key)
                                           throws java.io.IOException

Deprecated.

Returns the full details for a license WARNING: This uses a PREVIEW API.

Parameters:

key - The license key provided from the API

Returns:

The license details

Throws:

java.io.IOException

See Also:

GHLicense.getKey()

getMyOrganizations

public java.util.Map<java.lang.String,GHOrganization> getMyOrganizations()
                                                                  throws java.io.IOException

/** This method returns a shallowly populated organizations. To retrieve full organization details, you need to call getOrganization(String) TODO: make this automatic.

Throws:

java.io.IOException

getMyTeams

public java.util.Map<java.lang.String,java.util.Set<GHTeam>> getMyTeams()
                                                                 throws java.io.IOException

Gets complete map of organizations/teams that current user belongs to. Leverages the new GitHub API /user/teams made available recently to get in a single call the complete set of organizations, teams and permissions in a single call.

Throws:

java.io.IOException

getEvents

public java.util.List<GHEventInfo> getEvents()
                                      throws java.io.IOException

Public events visible to you. Equivalent of what's displayed on https://github.com/

Throws:

java.io.IOException

getGist

public GHGist getGist(java.lang.String id)
               throws java.io.IOException

Gets a sigle gist by ID.

Throws:

java.io.IOException

createGist

public GHGistBuilder createGist()

parseEventPayload

public <T extends GHEventPayload> T parseEventPayload(java.io.Reader r,
                                                      java.lang.Class<T> type)
                                               throws java.io.IOException

Parses the GitHub event object. This is primarily intended for receiving a POST HTTP call from a hook. Unfortunately, hook script payloads aren't self-descriptive, so you need to know the type of the payload you are expecting.

Throws:

java.io.IOException

createRepository

public GHRepository createRepository(java.lang.String name,
                                     java.lang.String description,
                                     java.lang.String homepage,
                                     boolean isPublic)
                              throws java.io.IOException

Deprecated. Use createRepository(String) that uses a builder pattern to let you control every aspect.

Creates a new repository.

Returns:

Newly created repository.

Throws:

java.io.IOException

createRepository

public GHCreateRepositoryBuilder createRepository(java.lang.String name)

Starts a builder that creates a new repository.

You use the returned builder to set various properties, then call GHCreateRepositoryBuilder.create() to finally createa repository.

To create a repository in an organization, see GHOrganization.createRepository(String, String, String, GHTeam, boolean)

createToken

public GHAuthorization createToken(java.util.Collection<java.lang.String> scope,
                                   java.lang.String note,
                                   java.lang.String noteUrl)
                            throws java.io.IOException

Creates a new authorization. The token created can be then used for connectUsingOAuth(String) in the future.

Throws:

java.io.IOException

See Also:

Documentation

isCredentialValid

public boolean isCredentialValid()
                          throws java.io.IOException

Ensures that the credential is valid.

Throws:

java.io.IOException

checkApiUrlValidity

public void checkApiUrlValidity()
                         throws java.io.IOException

Tests the connection.

Verify that the API URL and credentials are valid to access this GitHub.

This method returns normally if the endpoint is reachable and verified to be GitHub API URL. Otherwise this method throws IOException to indicate the problem.

Throws:

java.io.IOException

searchIssues

public GHIssueSearchBuilder searchIssues()

Search issues.

searchUsers

public GHUserSearchBuilder searchUsers()

Search users.

searchRepositories

public GHRepositorySearchBuilder searchRepositories()

Search repositories.

searchContent

public GHContentSearchBuilder searchContent()

Search content.

listNotifications

public GHNotificationStream listNotifications()

List all the notifications.

listAllPublicRepositories

public PagedIterable<GHRepository> listAllPublicRepositories()

This provides a dump of every public repository, in the order that they were created.

See Also:

documentation

listAllPublicRepositories

public PagedIterable<GHRepository> listAllPublicRepositories(java.lang.String since)

This provides a dump of every public repository, in the order that they were created.

Parameters:

since - The integer ID of the last Repository that you’ve seen. See GHObject.getId()

See Also:

documentation

renderMarkdown

public java.io.Reader renderMarkdown(java.lang.String text)
                              throws java.io.IOException

Render a Markdown document in raw mode.

It takes a Markdown document as plaintext and renders it as plain Markdown without a repository context (just like a README.md file is rendered – this is the simplest way to preview a readme online).

Throws:

java.io.IOException

See Also:

GHRepository.renderMarkdown(String, MarkdownMode)