Package org.kohsuke.github

Class 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 Detail

      • 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

      • 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

      • 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

      • listOrganizations

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

      • 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

      • 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:
        List Plans

      • 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

      • 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:
        Get a user's Marketplace purchases

      • 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

      • 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

      • 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

      • 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:
        docs

      • 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:
        Get Meta

      • 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

      • searchIssues

        public GHIssueSearchBuilder searchIssues()
        Search issues.
        Returns:
        the gh issue 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:
        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 numeric ID of the last Repository that you’ve seen. See GHObject.getId()
        Returns:
        the paged iterable
        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).

        Parameters:
        text - the text
        Returns:
        the reader
        Throws:
        IOException - the io exception
        See Also:
        GHRepository#renderMarkdown(String, MarkdownMode)

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