Package org.kohsuke.github

Class GitHubBuilder

java.lang.Object
org.kohsuke.github.GitHubBuilder
All Implemented Interfaces:
Cloneable
public class GitHubBuilder extends Object implements Cloneable
Configures connection details and produces GitHub.
Since:
1.59

  • Constructor Details

    • GitHubBuilder

      public GitHubBuilder()
      Instantiates a new Git hub builder.

  • Method Details

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

    • withJwtToken

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

    • withConnector

      @Deprecated public GitHubBuilder withConnector(@Nonnull HttpConnector connector)
      Deprecated.
      With connector git hub builder.
      Parameters:
      connector - the connector
      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:

    • withRateLimitHandler

      public GitHubBuilder withRateLimitHandler(GitHubRateLimitHandler handler)
      Adds a GitHubRateLimitHandler 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, GitHubRateLimitHandler.onError(GitHubConnectorResponse) 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:

    • withAbuseLimitHandler

      @Deprecated public GitHubBuilder withAbuseLimitHandler(AbuseLimitHandler handler)
      Deprecated.
      Adds a AbuseLimitHandler to this GitHubBuilder.

      When a client sends too many requests in a short time span, GitHub may return an error and set a header telling the client to not make any more request for some period of time. If this happens, AbuseLimitHandler.onError(IOException, HttpURLConnection) will be called.

      Parameters:
      handler - the handler
      Returns:
      the git hub builder

    • withAbuseLimitHandler

      public GitHubBuilder withAbuseLimitHandler(GitHubAbuseLimitHandler handler)
      Adds a GitHubAbuseLimitHandler to this GitHubBuilder.

      When a client sends too many requests in a short time span, GitHub may return an error and set a header telling the client to not make any more request for some period of time. If this happens, GitHubAbuseLimitHandler.onError(GitHubConnectorResponse) will be called.

      Parameters:
      handler - the handler
      Returns:
      the git hub builder

    • withRateLimitChecker

      public GitHubBuilder withRateLimitChecker(@Nonnull RateLimitChecker coreRateLimitChecker)
      Adds a RateLimitChecker for the Core API for this GitHubBuilder.
      Parameters:
      coreRateLimitChecker - the RateLimitChecker for core GitHub API requests
      Returns:
      the git hub builder
      See Also:

    • 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

    • build

      public GitHub build() throws IOException
      Builds a GitHub instance.
      Returns:
      the git hub
      Throws:
      IOException - the io exception

    • clone

      public GitHubBuilder clone()
      Clone.
      Overrides:
      clone in class Object
      Returns:
      the git hub builder