Package org.kohsuke.github

Class GitHubBuilder

  • All Implemented Interfaces:
    Cloneable
    public class GitHubBuilder
extends Object
implements Cloneable
    Configures connection details and produces GitHub.
    Since:
    1.59

    • Constructor Detail

      • GitHubBuilder

        public GitHubBuilder()
        Instantiates a new Git hub builder.

    • Method Detail

      • fromEnvironment

        @Deprecated
public static GitHubBuilder fromEnvironment​(String loginVariableName,
                                            String passwordVariableName,
                                            String oauthVariableName)
                                     throws IOException
        Deprecated.
        Use fromEnvironment() to pick up standard set of environment variables, so that different clients of this library will all recognize one consistent set of coordinates.
        From environment git hub builder.
        Parameters:
        loginVariableName - the login variable name
        passwordVariableName - the password variable name
        oauthVariableName - the oauth variable name
        Returns:
        the git hub builder
        Throws:
        IOException - the io exception

      • fromEnvironment

        @Deprecated
public static GitHubBuilder fromEnvironment​(String loginVariableName,
                                            String passwordVariableName,
                                            String oauthVariableName,
                                            String endpointVariableName)
                                     throws IOException
        Deprecated.
        Use fromEnvironment() to pick up standard set of environment variables, so that different clients of this library will all recognize one consistent set of coordinates.
        From environment git hub builder.
        Parameters:
        loginVariableName - the login variable name
        passwordVariableName - the password variable name
        oauthVariableName - the oauth variable name
        endpointVariableName - the endpoint variable name
        Returns:
        the git hub builder
        Throws:
        IOException - the io exception

      • fromEnvironment

        public static GitHubBuilder fromEnvironment()
                                     throws IOException
        Creates GitHubBuilder by picking up coordinates from environment variables.

        The following environment variables are recognized:

        • GITHUB_LOGIN: username like 'kohsuke'
        • GITHUB_PASSWORD: raw password
        • GITHUB_OAUTH: OAuth token to login
        • GITHUB_ENDPOINT: URL of the API endpoint
        • GITHUB_JWT: JWT token to login

        See class javadoc for the relationship between these coordinates.

        For backward compatibility, the following environment variables are recognized but discouraged: login, password, oauth

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

      • fromPropertyFile

        public static GitHubBuilder fromPropertyFile()
                                      throws IOException
        From property file git hub builder.
        Returns:
        the git hub builder
        Throws:
        IOException - the io exception

      • fromPropertyFile

        public static GitHubBuilder fromPropertyFile​(String propertyFileName)
                                      throws IOException
        From property file git hub builder.
        Parameters:
        propertyFileName - the property file name
        Returns:
        the git hub builder
        Throws:
        IOException - the io exception

      • fromProperties

        public static GitHubBuilder fromProperties​(Properties props)
        From properties git hub builder.
        Parameters:
        props - the props
        Returns:
        the git hub builder

      • withEndpoint

        public GitHubBuilder withEndpoint​(String endpoint)
        With endpoint git hub builder.
        Parameters:
        endpoint - The URL of GitHub (or GitHub enterprise) API endpoint, such as "https://api.github.com" or "https://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.
        Returns:
        the git hub builder

      • withPassword

        public GitHubBuilder withPassword​(String user,
                                  String password)
        With password git hub builder.
        Parameters:
        user - the user
        password - the password
        Returns:
        the git hub builder

      • withOAuthToken

        public GitHubBuilder withOAuthToken​(String oauthToken)
        With o auth token git hub builder.
        Parameters:
        oauthToken - the oauth token
        Returns:
        the git hub builder

      • withOAuthToken

        public GitHubBuilder withOAuthToken​(String oauthToken,
                                    String user)
        With o auth token git hub builder.
        Parameters:
        oauthToken - the oauth token
        user - the user
        Returns:
        the git hub builder

      • withAuthorizationProvider

        public GitHubBuilder withAuthorizationProvider​(AuthorizationProvider authorizationProvider)
        Configures a AuthorizationProvider for this builder There can be only one authorization provider per client instance.
        Parameters:
        authorizationProvider - the authorization provider
        Returns:
        the git hub builder

      • withAppInstallationToken

        public GitHubBuilder withAppInstallationToken​(String appInstallationToken)
        Configures GitHubBuilder with Installation Token generated by the GitHub Application.
        Parameters:
        appInstallationToken - A string containing the GitHub App installation token
        Returns:
        the configured Builder from given GitHub App installation token.
        See Also:
        GHAppInstallation#createToken(java.util.Map)

      • withJwtToken

        public GitHubBuilder withJwtToken​(String jwtToken)
        With jwt token git hub builder.
        Parameters:
        jwtToken - the jwt token
        Returns:
        the git hub builder

      • withConnector

        public GitHubBuilder withConnector​(GitHubConnector connector)
        With connector git hub builder.
        Parameters:
        connector - the connector
        Returns:
        the git hub builder

      • withRateLimitHandler

        public GitHubBuilder withRateLimitHandler​(RateLimitHandler handler)
        Adds a RateLimitHandler to this GitHubBuilder.

        GitHub allots a certain number of requests to each user or application per period of time (usually per hour). The number of requests remaining is returned in the response header and can also be requested using GitHub.getRateLimit(). This requests per interval is referred to as the "rate limit".

        When the remaining number of requests reaches zero, the next request will return an error. If this happens, RateLimitHandler.onError(IOException, HttpURLConnection) will be called.

        NOTE: GitHub treats clients that exceed their rate limit very harshly. If possible, clients should avoid exceeding their rate limit. Consider adding a RateLimitChecker to automatically check the rate limit for each request and wait if needed.

        Parameters:
        handler - the handler
        Returns:
        the git hub builder
        See Also:
        withRateLimitChecker(RateLimitChecker)

      • withRateLimitChecker

        public GitHubBuilder withRateLimitChecker​(@Nonnull
                                          RateLimitChecker rateLimitChecker,
                                          @Nonnull
                                          RateLimitTarget rateLimitTarget)
        Adds a RateLimitChecker to this GitHubBuilder.

        GitHub allots a certain number of requests to each user or application per period of time (usually per hour). The number of requests remaining is returned in the response header and can also be requested using GitHub.getRateLimit(). This requests per interval is referred to as the "rate limit".

        GitHub prefers that clients stop before exceeding their rate limit rather than stopping after they exceed it. The RateLimitChecker is called before each request to check the rate limit and wait if the checker criteria are met.

        Checking your rate limit using GitHub.getRateLimit() does not effect your rate limit, but each GitHub instance will attempt to cache and reuse the last seen rate limit rather than making a new request.

        Parameters:
        rateLimitChecker - the RateLimitChecker for requests
        rateLimitTarget - the RateLimitTarget specifying which rate limit record to check
        Returns:
        the git hub builder

      • withProxy

        public GitHubBuilder withProxy​(Proxy p)
        Configures connector that uses HTTP library in JRE but use a specific proxy, instead of the system default one.
        Parameters:
        p - the p
        Returns:
        the git hub builder