Package 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 Details

    • connect

      public static GitHub connect() throws IOException
      Obtains the credential from "~/.github" or from the System Environment Properties.
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connectToEnterprise

      @Deprecated public static GitHub connectToEnterprise(String apiUrl, String oauthAccessToken) throws IOException
      Deprecated.
      Use connectToEnterpriseWithOAuth(String, String, String)
      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.
      oauthAccessToken - the oauth access token
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connectToEnterpriseWithOAuth

      public static GitHub connectToEnterpriseWithOAuth(String apiUrl, String login, 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.
      login - the login
      oauthAccessToken - the oauth access token
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connectToEnterprise

      @Deprecated public static GitHub connectToEnterprise(String apiUrl, String login, String password) throws IOException
      Deprecated.
      Use with caution. Login with password is not a preferred method.
      Version that connects to GitHub Enterprise.
      Parameters:
      apiUrl - the api url
      login - the login
      password - the password
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connect

      public static GitHub connect(String login, String oauthAccessToken) throws IOException
      Connect git hub.
      Parameters:
      login - the login
      oauthAccessToken - the oauth access token
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connect

      @Deprecated public static GitHub connect(String login, String oauthAccessToken, String password) throws IOException
      Deprecated.
      Use connectUsingOAuth(String).
      Connect git hub.
      Parameters:
      login - the login
      oauthAccessToken - the oauth access token
      password - the password
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connectUsingPassword

      @Deprecated public static GitHub connectUsingPassword(String login, String password) throws IOException
      Deprecated.
      Use connectUsingOAuth(String) instead.
      Connect using password git hub.
      Parameters:
      login - the login
      password - the password
      Returns:
      the git hub
      Throws:
      IOException - the io exception
      See Also:

    • connectUsingOAuth

      public static GitHub connectUsingOAuth(String oauthAccessToken) throws IOException
      Connect using o auth git hub.
      Parameters:
      oauthAccessToken - the oauth access token
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connectUsingOAuth

      public static GitHub connectUsingOAuth(String githubServer, String oauthAccessToken) throws IOException
      Connect using o auth git hub.
      Parameters:
      githubServer - the github server
      oauthAccessToken - the oauth access token
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connectAnonymously

      public static GitHub connectAnonymously() throws IOException
      Connects to GitHub anonymously.

      All operations that require authentication will fail.

      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • connectToEnterpriseAnonymously

      public static GitHub connectToEnterpriseAnonymously(String apiUrl) throws IOException
      Connects to GitHub Enterprise anonymously.

      All operations that require authentication will fail.

      Parameters:
      apiUrl - the api url
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • offline

      public static GitHub offline()
      An offline-only GitHub useful for parsing event notification from an unknown source.

      All operations that require a connection will fail.

      Returns:
      An offline-only GitHub.

    • isAnonymous

      public boolean isAnonymous()
      Is this an anonymous connection.
      Returns:
      true if operations that require authentication will fail.

    • isOffline

      public boolean isOffline()
      Is this an always offline "connection".
      Returns:
      true if this is an always offline "connection".

    • getConnector

      @Deprecated public HttpConnector getConnector()
      Deprecated.
      HttpConnector has been replaced by GitHubConnector which is generally not useful outside of this library. If you are using this method, file an issue describing your use case.
      Gets connector.
      Returns:
      the connector

    • setConnector

      @Deprecated public void setConnector(@Nonnull HttpConnector connector)
      Deprecated.
      HttpConnector should not be changed. If you find yourself needing to do this, file an issue.
      Sets the custom connector used to make requests to GitHub.
      Parameters:
      connector - the connector

    • getApiUrl

      public String getApiUrl()
      Gets api url.
      Returns:
      the api url

    • getRateLimit

      @Nonnull public GHRateLimit getRateLimit() throws IOException
      Gets the current full rate limit information from the server. For some versions of GitHub Enterprise, the /rate_limit endpoint returns a 404 Not Found. In that case, the most recent GHRateLimit information will be returned, including rate limit information returned in the response header for this request in if was present. For most use cases it would be better to implement a RateLimitChecker and add it via GitHubBuilder.withRateLimitChecker(RateLimitChecker).
      Returns:
      the rate limit
      Throws:
      IOException - the io exception

    • lastRateLimit

      @Nonnull @Deprecated public GHRateLimit lastRateLimit()
      Deprecated.
      implement a RateLimitChecker and add it via GitHubBuilder.withRateLimitChecker(RateLimitChecker).
      Returns the most recently observed rate limit data or null if either there is no rate limit (for example GitHub Enterprise) or if no requests have been made.
      Returns:
      the most recently observed rate limit data or null.

    • rateLimit

      @Nonnull @Deprecated public GHRateLimit rateLimit() throws IOException
      Deprecated.
      implement a RateLimitChecker and add it via GitHubBuilder.withRateLimitChecker(RateLimitChecker).
      Gets the current rate limit while trying not to actually make any remote requests unless absolutely necessary.
      Returns:
      the current rate limit data.
      Throws:
      IOException - if we couldn't get the current rate limit data.

    • getMyself

      @WithBridgeMethods(GHUser.class) public GHMyself getMyself() throws IOException
      Gets the GHUser that represents yourself.
      Returns:
      the myself
      Throws:
      IOException - the io exception

    • getUser

      public GHUser getUser(String login) throws IOException
      Obtains the object that represents the named user.
      Parameters:
      login - the login
      Returns:
      the user
      Throws:
      IOException - the io exception

    • refreshCache

      public void refreshCache()
      clears all cached data in order for external changes (modifications and del) to be reflected.

    • getUser

      protected GHUser getUser(GHUser orig)
      Interns the given GHUser.
      Parameters:
      orig - the orig
      Returns:
      the user

    • getOrganization

      public GHOrganization getOrganization(String name) throws IOException
      Gets GHOrganization specified by name.
      Parameters:
      name - the name
      Returns:
      the organization
      Throws:
      IOException - the io exception

    • listOrganizations

      public PagedIterable<GHOrganization> listOrganizations()
      Gets a list of all organizations.
      Returns:
      the paged iterable

    • listOrganizations

      public PagedIterable<GHOrganization> listOrganizations(String since)
      Gets a list of all organizations starting after the organization identifier specified by 'since'.
      Parameters:
      since - the since
      Returns:
      the paged iterable
      See Also:

    • getRepository

      public GHRepository getRepository(String name) throws IOException
      Gets the repository object from 'owner/repo' string that GitHub calls as "repository name".
      Parameters:
      name - the name
      Returns:
      the repository
      Throws:
      IOException - the io exception
      See Also:

    • getRepositoryById

      @Deprecated public GHRepository getRepositoryById(String id) throws IOException
      Deprecated.
      Do not use this method. It was added due to misunderstanding of the type of parameter. Use getRepositoryById(long) instead
      Gets the repository object from its ID.
      Parameters:
      id - the id
      Returns:
      the repository by id
      Throws:
      IOException - the io exception

    • getRepositoryById

      public GHRepository getRepositoryById(long id) throws IOException
      Gets the repository object from its ID.
      Parameters:
      id - the id
      Returns:
      the repository by id
      Throws:
      IOException - the io exception

    • listLicenses

      public PagedIterable<GHLicense> listLicenses() throws IOException
      Returns a list of popular open source licenses.
      Returns:
      a list of popular open source licenses
      Throws:
      IOException - the io exception
      See Also:

    • listUsers

      public PagedIterable<GHUser> listUsers() throws IOException
      Returns a list of all users.
      Returns:
      the paged iterable
      Throws:
      IOException - the io exception

    • getLicense

      public GHLicense getLicense(String key) throws IOException
      Returns the full details for a license.
      Parameters:
      key - The license key provided from the API
      Returns:
      The license details
      Throws:
      IOException - the io exception
      See Also:

    • listMarketplacePlans

      public PagedIterable<GHMarketplacePlan> listMarketplacePlans() throws IOException
      Returns a list all plans for your Marketplace listing

      GitHub Apps must use a JWT to access this endpoint.

      OAuth Apps must use basic authentication with their client ID and client secret to access this endpoint.

      Returns:
      the paged iterable
      Throws:
      IOException - the io exception
      See Also:

    • getMyInvitations

      public List<GHInvitation> getMyInvitations() throws IOException
      Gets complete list of open invitations for current user.
      Returns:
      the my invitations
      Throws:
      IOException - the io exception

    • getMyOrganizations

      public Map<String,GHOrganization> getMyOrganizations() throws IOException
      This method returns shallowly populated organizations.

      To retrieve full organization details, you need to call getOrganization(String) TODO: make this automatic.

      Returns:
      the my organizations
      Throws:
      IOException - the io exception

    • getMyMarketplacePurchases

      public PagedIterable<GHMarketplaceUserPurchase> getMyMarketplacePurchases() throws IOException
      Returns only active subscriptions.

      You must use a user-to-server OAuth access token, created for a user who has authorized your GitHub App, to access this endpoint

      OAuth Apps must authenticate using an OAuth token.

      Returns:
      the paged iterable of GHMarketplaceUserPurchase
      Throws:
      IOException - the io exception
      See Also:

    • getUserPublicOrganizations

      public Map<String,GHOrganization> getUserPublicOrganizations(GHUser user) throws IOException
      Alias for getUserPublicOrganizations(String).
      Parameters:
      user - the user
      Returns:
      the user public organizations
      Throws:
      IOException - the io exception

    • getUserPublicOrganizations

      public Map<String,GHOrganization> getUserPublicOrganizations(String login) throws IOException
      This method returns a shallowly populated organizations.

      To retrieve full organization details, you need to call getOrganization(String)

      Parameters:
      login - the user to retrieve public Organization membership information for
      Returns:
      the public Organization memberships for the user
      Throws:
      IOException - the io exception

    • 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.

      Returns:
      the my teams
      Throws:
      IOException - the io exception

    • getTeam

      @Deprecated public GHTeam getTeam(int id) throws IOException
      Deprecated.
      Use GHOrganization.getTeam(long)
      Gets a single team by ID.

      This method is no longer supported and throws an UnsupportedOperationException.

      Parameters:
      id - the id
      Returns:
      the team
      Throws:
      IOException - the io exception
      See Also:

    • getEvents

      public List<GHEventInfo> getEvents() throws IOException
      Public events visible to you. Equivalent of what's displayed on https://github.com/
      Returns:
      the events
      Throws:
      IOException - the io exception

    • getUserPublicEvents

      public List<GHEventInfo> getUserPublicEvents(String login) throws IOException
      List public events for a user see API documentation
      Parameters:
      login - the login (user) to look public events for
      Returns:
      the events
      Throws:
      IOException - the io exception

    • getGist

      public GHGist getGist(String id) throws IOException
      Gets a single gist by ID.
      Parameters:
      id - the id
      Returns:
      the gist
      Throws:
      IOException - the io exception

    • createGist

      public GHGistBuilder createGist()
      Create gist gh gist builder.
      Returns:
      the gh gist builder

    • 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.

      Type Parameters:
      T - the type parameter
      Parameters:
      r - the r
      type - the type
      Returns:
      the t
      Throws:
      IOException - the io exception

    • createRepository

      @Deprecated 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.
      Parameters:
      name - the name
      description - the description
      homepage - the homepage
      isPublic - the is public
      Returns:
      Newly created repository.
      Throws:
      IOException - the io exception

    • 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 create a repository.

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

      Parameters:
      name - the name
      Returns:
      the gh create repository builder

    • 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.

      Parameters:
      scope - the scope
      note - the note
      noteUrl - the note url
      Returns:
      the gh authorization
      Throws:
      IOException - the io exception
      See Also:

    • createToken

      public GHAuthorization createToken(Collection<String> scope, String note, String noteUrl, Supplier<String> OTP) throws IOException
      Creates a new authorization using an OTP.

      Start by running createToken, if exception is thrown, prompt for OTP from user

      Once OTP is received, call this token request

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

      Parameters:
      scope - the scope
      note - the note
      noteUrl - the note url
      OTP - the otp
      Returns:
      the gh authorization
      Throws:
      IOException - the io exception
      See Also:

    • createOrGetAuth

      public GHAuthorization createOrGetAuth(String clientId, String clientSecret, List<String> scopes, String note, String note_url) throws IOException
      Create or get auth gh authorization.
      Parameters:
      clientId - the client id
      clientSecret - the client secret
      scopes - the scopes
      note - the note
      note_url - the note url
      Returns:
      the gh authorization
      Throws:
      IOException - the io exception
      See Also:

    • deleteAuth

      public void deleteAuth(long id) throws IOException
      Delete auth.
      Parameters:
      id - the id
      Throws:
      IOException - the io exception
      See Also:

    • checkAuth

      public GHAuthorization checkAuth(@Nonnull String clientId, @Nonnull String accessToken) throws IOException
      Check auth gh authorization.
      Parameters:
      clientId - the client id
      accessToken - the access token
      Returns:
      the gh authorization
      Throws:
      IOException - the io exception
      See Also:

    • resetAuth

      public GHAuthorization resetAuth(@Nonnull String clientId, @Nonnull String accessToken) throws IOException
      Reset auth gh authorization.
      Parameters:
      clientId - the client id
      accessToken - the access token
      Returns:
      the gh authorization
      Throws:
      IOException - the io exception
      See Also:

    • listMyAuthorizations

      public PagedIterable<GHAuthorization> listMyAuthorizations() throws IOException
      Returns a list of all authorizations.
      Returns:
      the paged iterable
      Throws:
      IOException - the io exception
      See Also:

    • getApp

      @Preview(MACHINE_MAN) public GHApp getApp() throws IOException
      Returns the GitHub App associated with the authentication credentials used.

      You must use a JWT to access this endpoint.

      Returns:
      the app
      Throws:
      IOException - the io exception
      See Also:

    • getApp

      public GHApp getApp(@Nonnull String slug) throws IOException
      Returns the GitHub App identified by the given slug
      Parameters:
      slug - the slug of the application
      Returns:
      the app
      Throws:
      IOException - the IO exception
      See Also:

    • createAppFromManifest

      public GHAppFromManifest createAppFromManifest(@Nonnull String code) throws IOException
      Creates a GitHub App from a manifest.
      Parameters:
      code - temporary code returned during the manifest flow
      Returns:
      the app
      Throws:
      IOException - the IO exception
      See Also:

    • getInstallation

      @Preview(MACHINE_MAN) public GHAuthenticatedAppInstallation getInstallation() throws IOException
      Returns the GitHub App Installation associated with the authentication credentials used.

      You must use an installation token to access this endpoint; otherwise consider getApp() and its various ways of retrieving installations.

      Returns:
      the app
      Throws:
      IOException - the io exception
      See Also:

    • isCredentialValid

      public boolean isCredentialValid()
      Ensures that the credential is valid.
      Returns:
      the boolean

    • getMeta

      public GHMeta getMeta() throws IOException
      Provides a list of GitHub's IP addresses.
      Returns:
      an instance of GHMeta
      Throws:
      IOException - if the credentials supplied are invalid or if you're trying to access it as a GitHub App via the JWT authentication
      See Also:

    • getProject

      public GHProject getProject(long id) throws IOException
      Gets project.
      Parameters:
      id - the id
      Returns:
      the project
      Throws:
      IOException - the io exception

    • getProjectColumn

      public GHProjectColumn getProjectColumn(long id) throws IOException
      Gets project column.
      Parameters:
      id - the id
      Returns:
      the project column
      Throws:
      IOException - the io exception

    • getProjectCard

      public GHProjectCard getProjectCard(long id) throws IOException
      Gets project card.
      Parameters:
      id - the id
      Returns:
      the project card
      Throws:
      IOException - the io exception

    • checkApiUrlValidity

      public void checkApiUrlValidity() throws 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:
      IOException - the io exception

    • searchCommits

      @Preview(CLOAK) public GHCommitSearchBuilder searchCommits()
      Search commits.
      Returns:
      the gh commit search builder

    • searchIssues

      public GHIssueSearchBuilder searchIssues()
      Search issues.
      Returns:
      the gh issue search builder

    • searchPullRequests

      public GHPullRequestSearchBuilder searchPullRequests()
      Search for pull requests.
      Returns:
      gh pull request search builder

    • searchUsers

      public GHUserSearchBuilder searchUsers()
      Search users.
      Returns:
      the gh user search builder

    • searchRepositories

      public GHRepositorySearchBuilder searchRepositories()
      Search repositories.
      Returns:
      the gh repository search builder

    • searchContent

      public GHContentSearchBuilder searchContent()
      Search content.
      Returns:
      the gh content search builder

    • listNotifications

      public GHNotificationStream listNotifications()
      List all the notifications.
      Returns:
      the gh notification stream

    • listAllPublicRepositories

      public PagedIterable<GHRepository> listAllPublicRepositories()
      This provides a dump of every public repository, in the order that they were created.
      Returns:
      the paged iterable
      See Also:

    • 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 numeric ID of the last Repository that you’ve seen. See GHObject.getId()
      Returns:
      the paged iterable
      See Also:

    • 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).

      Parameters:
      text - the text
      Returns:
      the reader
      Throws:
      IOException - the io exception
      See Also:

    • getMappingObjectWriter

      @Nonnull public static com.fasterxml.jackson.databind.ObjectWriter getMappingObjectWriter()
      Gets an ObjectWriter that can be used to convert data objects in this library to JSON. If you must convert data object in this library to JSON, the ObjectWriter returned by this method is the only supported way of doing so. This ObjectWriter can be used to convert any library data object to JSON without throwing an exception. WARNING: While the JSON generated is generally expected to be stable, it is not part of the API of this library and may change without warning. Use with extreme caution.
      Returns:
      an ObjectWriter instance that can be further configured.

    • getMappingObjectReader

      @Nonnull public static com.fasterxml.jackson.databind.ObjectReader getMappingObjectReader()
      Gets an ObjectReader that can be used to convert JSON into library data objects. If you must manually create library data objects from JSON, the ObjectReader returned by this method is the only supported way of doing so. WARNING: Objects generated from this method have limited functionality. They will not throw when being crated from valid JSON matching the expected object, but they are not guaranteed to be usable beyond that. Use with extreme caution.
      Returns:
      an ObjectReader instance that can be further configured.