Package io.github.intisy.gradle.github.impl

Class GitHub

java.lang.Object
io.github.intisy.gradle.github.impl.GitHub
public class GitHub extends Object
GitHub helper class for managing GitHub repositories, releases, and assets. Provides methods for cloning, pulling, and fetching repository information.

  • Constructor Details

    • GitHub

      public GitHub(Logger logger, ResourcesExtension resourcesExtension, GithubExtension githubExtension)
      Constructs a new GitHub helper instance.
      Parameters:
      logger - the logger instance for debug and error messages
      resourcesExtension - the resources extension containing repository configuration
      githubExtension - the github extension containing access token configuration

  • Method Details

    • getApiKey

      public String getApiKey()
      Gets the GitHub token used for REST calls and HTTPS git operations, resolving it from the auth extension (or the deprecated accessToken fallback). Cached after the first resolution.
      Returns:
      the resolved token, or null if none is configured

    • getSshKey

      public String getSshKey()
      Gets the SSH private key contents used for git transport, resolving it from auth.sshKey (or the deprecated accessToken fallback when that holds an SSH key). Cached after the first resolution.
      Returns:
      the SSH private key contents, or null if none is configured

    • getResourceRepoName

      public String getResourceRepoName()
      Extracts the repository name from the configured repository URL.
      Returns:
      the repository name, or null if not configured

    • getResourceRepoOwner

      public String getResourceRepoOwner()
      Extracts the repository owner from the configured repository URL.
      Returns:
      the repository owner, or null if not configured

    • getCredentialsProvider

      public org.eclipse.jgit.transport.CredentialsProvider getCredentialsProvider(String repoOwner)
      Creates a credentials provider for Git operations.
      Parameters:
      repoOwner - the repository owner for authentication
      Returns:
      the credentials provider, or null if SSH authentication is used

    • cloneRepository

      public void cloneRepository(File path, String repoOwner, String repoName) throws org.eclipse.jgit.api.errors.GitAPIException
      Clones a GitHub repository to the specified path.
      Parameters:
      path - the directory to clone the repository into
      repoOwner - the repository owner
      repoName - the repository name
      Throws:
      org.eclipse.jgit.api.errors.GitAPIException - if the clone operation fails

    • cloneRepository

      public void cloneRepository(File path) throws org.eclipse.jgit.api.errors.GitAPIException
      Clones the configured resource repository to the specified path.
      Parameters:
      path - the directory to clone the repository into
      Throws:
      org.eclipse.jgit.api.errors.GitAPIException - if the clone operation fails

    • doesRepoExist

      public boolean doesRepoExist(File path)
      Checks if a Git repository exists at the specified path.
      Parameters:
      path - the directory to check
      Returns:
      true if a repository exists, false otherwise

    • isRepoUpToDate

      public boolean isRepoUpToDate(File path)
      Checks if the local repository is up-to-date with the remote.
      Parameters:
      path - the repository directory
      Returns:
      true if up-to-date, false otherwise

    • pullRepository

      public void pullRepository(File path, String branch) throws org.eclipse.jgit.api.errors.GitAPIException, IOException
      Pulls the latest changes from the remote repository.
      Parameters:
      path - the repository directory
      branch - the branch to pull, or null for the current branch
      Throws:
      org.eclipse.jgit.api.errors.GitAPIException - if the pull operation fails
      IOException - if an I/O error occurs

    • pullRepository

      public void pullRepository(File path) throws org.eclipse.jgit.api.errors.GitAPIException, IOException
      Pulls the latest changes from the current branch of the remote repository.
      Parameters:
      path - the repository directory
      Throws:
      org.eclipse.jgit.api.errors.GitAPIException - if the pull operation fails
      IOException - if an I/O error occurs

    • cloneOrPullRepository

      public void cloneOrPullRepository(File path, String repoOwner, String repoName, String branch) throws org.eclipse.jgit.api.errors.GitAPIException, IOException
      Clones a repository if it doesn't exist, otherwise pulls the latest changes.
      Parameters:
      path - the repository directory
      repoOwner - the repository owner
      repoName - the repository name
      branch - the branch to pull, or null for the current branch
      Throws:
      org.eclipse.jgit.api.errors.GitAPIException - if the clone or pull operation fails
      IOException - if an I/O error occurs

    • cloneOrPullRepository

      public void cloneOrPullRepository(File path, String branch) throws org.eclipse.jgit.api.errors.GitAPIException, IOException
      Clones the configured resource repository if it doesn't exist, otherwise pulls the latest changes.
      Parameters:
      path - the repository directory
      branch - the branch to pull, or null for the current branch
      Throws:
      org.eclipse.jgit.api.errors.GitAPIException - if the clone or pull operation fails
      IOException - if an I/O error occurs

    • cloneOrPullRepository

      public void cloneOrPullRepository(File path) throws org.eclipse.jgit.api.errors.GitAPIException, IOException
      Clones the configured resource repository if it doesn't exist, otherwise pulls the latest changes from the current branch.
      Parameters:
      path - the repository directory
      Throws:
      org.eclipse.jgit.api.errors.GitAPIException - if the clone or pull operation fails
      IOException - if an I/O error occurs

    • fetchReleaseByTag

      public com.google.gson.JsonObject fetchReleaseByTag(String repoOwner, String repoName, String version)
      Attempts to fetch a GitHub release by tag, trying the given tag first and then a "v"-prefixed or "v"-stripped variant as a fallback.
      Parameters:
      repoOwner - the repository owner
      repoName - the repository name
      version - the release version tag as declared by the consumer
      Returns:
      the parsed release JSON object
      Throws:
      RuntimeException - if neither tag variant resolves to a release

    • selectJarAsset

      public com.google.gson.JsonObject selectJarAsset(com.google.gson.JsonArray assets, String repoName, String version)
      Selects the best JAR asset from a release using a prioritized matching strategy: (1) exact repoName.jar, (2) repoName-version.jar, (3) repoName-standalone.jar, (4) first .jar not ending in -sources.jar or -javadoc.jar.
      Parameters:
      assets - the release assets JSON array
      repoName - the repository name
      version - the release version tag
      Returns:
      the selected asset JSON object, or null if no suitable JAR found

    • getAsset

      public File getAsset(String repoOwner, String repoName, String version)
      Downloads and caches a release asset JAR file from a GitHub repository.
      Parameters:
      repoOwner - the repository owner
      repoName - the repository name
      version - the release version tag
      Returns:
      the downloaded JAR file

    • getAsset

      public File getAsset(String version)
      Downloads and caches a release asset JAR file from the configured resource repository.
      Parameters:
      version - the release version tag
      Returns:
      the downloaded JAR file

    • readGithubDependencies

      public List<String[]> readGithubDependencies(File jar)
      Reads the embedded github-dependencies metadata from a JAR file. The metadata is stored at META-INF/github-dependencies.json and contains a JSON array of objects with group, name, and version fields. This location is safe from obfuscation tools (ProGuard, R8, etc.) which only process class files.
      Parameters:
      jar - the JAR file to read metadata from
      Returns:
      a list of dependency entries as [group, name, version] arrays, empty if no metadata found

    • getAssetWithTransitives

      public void getAssetWithTransitives(String repoOwner, String repoName, String version, Set<String> resolved, List<File> collected)
      Downloads a release asset JAR and recursively resolves its transitive GitHub dependencies. Each dependency's JAR is inspected for embedded META-INF/github-dependencies.json metadata, and any listed dependencies are downloaded recursively. A resolved-set prevents cycles and duplicate downloads.
      Parameters:
      repoOwner - the repository owner
      repoName - the repository name
      version - the release version tag
      resolved - set of already-resolved dependency keys ("owner:name:version") for cycle detection
      collected - list that all resolved JAR files (including transitives) are added to

    • getAssetWithClassifier

      public File getAssetWithClassifier(String repoOwner, String repoName, String version, String classifier)
      Downloads and caches a classifier-specific JAR asset from a GitHub release.

      The expected asset name on the release is repoName-classifier.jar. The file is cached under the same owner directory as getAsset(java.lang.String, java.lang.String, java.lang.String).

      Parameters:
      repoOwner - the repository owner
      repoName - the repository name
      version - the release version tag
      classifier - the artifact classifier (e.g. "api", "fat")
      Returns:
      the downloaded JAR file, or null if no matching asset exists in the release

    • getAllModuleAssets

      public void getAllModuleAssets(String repoOwner, String repoName, String version, List<File> collected)
      Downloads every module asset from a multi-module release (all assets named repoName-<classifier>.jar, excluding -sources.jar/-javadoc.jar). Backs the reserved :all classifier so a consumer can pull the whole library without listing each module. Each jar is cached under the same owner directory as getAsset(java.lang.String, java.lang.String, java.lang.String).
      Parameters:
      repoOwner - the repository owner
      repoName - the repository name
      version - the release version tag
      collected - list that the downloaded module JAR files are added to

    • downloadAsset

      @Deprecated public void downloadAsset(File direction, Object asset, String repoOwner, String repoName)
      Deprecated.
      Use downloadAssetFromUrl instead
      Downloads a GitHub release asset to the specified file location.
      Parameters:
      direction - the destination file
      asset - the GitHub asset object (no longer supported)
      repoOwner - the repository owner
      repoName - the repository name

    • getLatestRelease

      public com.google.gson.JsonObject getLatestRelease(String repoOwner, String repoName)
      Fetches the latest release from a GitHub repository.
      Parameters:
      repoOwner - the repository owner
      repoName - the repository name
      Returns:
      JSON object representing the latest release, or null if no releases exist

    • getLatestRelease

      public com.google.gson.JsonObject getLatestRelease()
      Fetches the latest release from the configured resource repository.
      Returns:
      JSON object representing the latest release, or null if no releases exist

    • getLatestVersion

      public String getLatestVersion(String repoOwner, String repoName)
      Gets the latest version tag from a GitHub repository.
      Parameters:
      repoOwner - the repository owner
      repoName - the repository name
      Returns:
      the latest version tag, or null if no releases exist

    • getLatestVersion

      public String getLatestVersion()
      Gets the latest version tag from the configured resource repository.
      Returns:
      the latest version tag, or null if no releases exist

    • getRemoteOwnerAndRepo

      public String[] getRemoteOwnerAndRepo(File projectDir)
      Reads the git remote "origin" URL from the project directory and parses it into [owner, repo]. Supports both HTTPS and SSH remote URLs.
      Parameters:
      projectDir - the root directory of the Git repository
      Returns:
      a two-element array {owner, repo}
      Throws:
      RuntimeException - if no "origin" remote is configured or the URL cannot be parsed

    • createRelease

      public com.google.gson.JsonObject createRelease(String owner, String repo, String tagName, String releaseName)
      Creates a GitHub release for the given tag, reusing the existing release if the tag already exists.

      If a release for tagName already exists it is returned as-is so that additional assets can still be uploaded to it without failing the build.

      Parameters:
      owner - the repository owner
      repo - the repository name
      tagName - the git tag for the release (GitHub auto-creates a lightweight tag if absent)
      releaseName - the human-readable release title; if null, defaults to tagName
      Returns:
      the release JSON object (contains upload_url)
      Throws:
      RuntimeException - if auth fails or the API errors

    • uploadReleaseAsset

      public void uploadReleaseAsset(String uploadUrl, File file, String assetName) throws IOException
      Uploads a file as a release asset to GitHub.
      Parameters:
      uploadUrl - the upload_url from the release object (URI template stripped automatically)
      file - the file to upload
      assetName - the asset name as it will appear in the release
      Throws:
      IOException - if the upload fails