Module org.kohsuke.github.api
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

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

      Returns:
      the GitHubBuilder
      Throws:
      IOException - the io exception

    • fromPropertyFile

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

    • fromPropertyFile

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

    • fromProperties

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

    • withEndpoint

      public GitHubBuilder withEndpoint(String endpoint)
      With endpoint GitHubBuilder.
      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 GitHubBuilder

    • withOAuthToken

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

    • withOAuthToken

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

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

    • 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 GitHubBuilder.
      Parameters:
      jwtToken - the jwt token
      Returns:
      the GitHubBuilder

    • withConnector

      public GitHubBuilder withConnector(GitHubConnector connector)
      With connector GitHubBuilder.
      Parameters:
      connector - the connector
      Returns:
      the GitHubBuilder

    • 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 GitHubBuilder
      See Also:

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

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

    • build

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

    • clone

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