org.kohsuke.github

Class GitHub

java.lang.Object

org.kohsuke.github.GitHub

public class GitHub
extends 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

Methods

Modifier and Type	Method and Description
void	checkApiUrlValidity() Ensures that the API URL is valid.
static GitHub	connect() Obtains the credential from "~/.github" or from the System Environment Properties.
static GitHub	connect(String login, String oauthAccessToken)
static GitHub	connect(String login, String oauthAccessToken, 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(String apiUrl, String oauthAccessToken) Version that connects to GitHub Enterprise.
static GitHub	connectToEnterprise(String apiUrl, String login, String password)
static GitHub	connectToEnterpriseAnonymously(String apiUrl) Connects to GitHub Enterprise anonymously.
static GitHub	connectUsingOAuth(String oauthAccessToken)
static GitHub	connectUsingOAuth(String githubServer, String oauthAccessToken)
static GitHub	connectUsingPassword(String login, String password)
GHGistBuilder	createGist()
GHCreateRepositoryBuilder	createRepository(String name) Starts a builder that creates a new repository.
GHRepository	createRepository(String name, String description, String homepage, boolean isPublic) Deprecated. Use createRepository(String) that uses a builder pattern to let you control every aspect.
GHAuthorization	createToken(Collection<String> scope, String note, String noteUrl) Creates a new authorization.
HttpConnector	getConnector()
List<GHEventInfo>	getEvents() Public events visible to you.
GHGist	getGist(String id) Gets a sigle gist by ID.
Map<String,GHOrganization>	getMyOrganizations() This method returns a shallowly populated organizations.
GHMyself	getMyself() Gets the GHUser that represents yourself.
Map<String,Set<GHTeam>>	getMyTeams() Gets complete map of organizations/teams that current user belongs to.
GHOrganization	getOrganization(String name)
GHRateLimit	getRateLimit() Gets the current rate limit.
GHRepository	getRepository(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(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(String since) This provides a dump of every public repository, in the order that they were created.
GHNotificationStream	listNotifications() List all the notifications.
<T extends GHEventPayload> T	parseEventPayload(Reader r, Class<T> type) Parses the GitHub event object.
void	refreshCache() clears all cached data in order for external changes (modifications and del
Reader	renderMarkdown(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 IOException

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

Throws:

IOException

connectToEnterprise

public static GitHub connectToEnterprise(String apiUrl,
                         String oauthAccessToken)
                                  throws 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:

IOException

connectToEnterprise

public static GitHub connectToEnterprise(String apiUrl,
                         String login,
                         String password)
                                  throws IOException

Throws:

IOException

connect

public static GitHub connect(String login,
             String oauthAccessToken)
                      throws IOException

Throws:

IOException

connect

public static GitHub connect(String login,
             String oauthAccessToken,
             String password)
                      throws 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:

IOException

connectUsingPassword

public static GitHub connectUsingPassword(String login,
                          String password)
                                   throws IOException

Throws:

IOException

connectUsingOAuth

public static GitHub connectUsingOAuth(String oauthAccessToken)
                                throws IOException

Throws:

IOException

connectUsingOAuth

public static GitHub connectUsingOAuth(String githubServer,
                       String oauthAccessToken)
                                throws IOException

Throws:

IOException

connectAnonymously

public static GitHub connectAnonymously()
                                 throws IOException

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

Throws:

IOException

connectToEnterpriseAnonymously

public static GitHub connectToEnterpriseAnonymously(String apiUrl)
                                             throws IOException

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

Throws:

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 IOException

Gets the current rate limit.

Throws:

IOException

getMyself

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

Gets the GHUser that represents yourself.

Throws:

IOException

getUser

public GHUser getUser(String login)
               throws IOException

Obtains the object that represents the named user.

Throws:

IOException

refreshCache

public void refreshCache()

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

getUser

protected GHUser getUser(GHUser orig)
                  throws IOException

Interns the given GHUser.

Throws:

IOException

getOrganization

public GHOrganization getOrganization(String name)
                               throws IOException

Throws:

IOException

getRepository

public GHRepository getRepository(String name)
                           throws IOException

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

Throws:

IOException

See Also:

GHRepository.getName()

getMyOrganizations

public Map<String,GHOrganization> getMyOrganizations()
                                              throws IOException

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

Throws:

IOException

getMyTeams

public Map<String,Set<GHTeam>> getMyTeams()
                                   throws 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:

IOException

getEvents

public List<GHEventInfo> getEvents()
                            throws IOException

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

Throws:

IOException

getGist

public GHGist getGist(String id)
               throws IOException

Gets a sigle gist by ID.

Throws:

IOException

createGist

public GHGistBuilder createGist()

parseEventPayload

public <T extends GHEventPayload> T parseEventPayload(Reader r,
                                             Class<T> type)
                                           throws 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:

IOException

createRepository

public GHRepository createRepository(String name,
                            String description,
                            String homepage,
                            boolean isPublic)
                              throws 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:

IOException

createRepository

public GHCreateRepositoryBuilder createRepository(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(Collection<String> scope,
                          String note,
                          String noteUrl)
                            throws IOException

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

Throws:

IOException

See Also:

Documentation

isCredentialValid

public boolean isCredentialValid()
                          throws IOException

Ensures that the credential is valid.

Throws:

IOException

checkApiUrlValidity

public void checkApiUrlValidity()
                         throws IOException

Ensures that the API URL is valid.

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:

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(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 Reader renderMarkdown(String text)
                      throws 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:

IOException

See Also:

GHRepository.renderMarkdown(String, MarkdownMode)