Consuming Dependencies

Consuming Dependencies

The plugin adds five dependency configurations that mirror the standard Gradle Java scopes. Each one resolves its JARs from GitHub releases instead of a Maven repository.

Dependency notation

"OWNER:REPO:VERSION"
"OWNER:REPO:VERSION:CLASSIFIER"

Segment	Description
OWNER	GitHub user or organisation that owns the repository
REPO	Repository name
VERSION	Release tag (e.g. 1.0.0, v1.0.0)
CLASSIFIER	(optional) Selects a specific artifact from a multi-JAR release

The tag matching is flexible: declaring 1.0.0 will also try v1.0.0, and vice versa.

Configurations

Configuration	Maps to Gradle scope	Requires
githubImplementation	implementation	java plugin
githubApi	api	java-library plugin
githubCompileOnly	compileOnly	java plugin
githubCompileOnlyApi	compileOnlyApi	java-library plugin
githubRuntimeOnly	runtimeOnly	java plugin

githubApi and githubCompileOnlyApi are silently skipped if the java-library plugin is not applied.

Examples

dependencies {
    // Default artifact (repo.jar)
    githubImplementation "my-org:my-library:1.0.0"

    // Specific classifier — downloads my-library-api.jar from the release
    githubImplementation "my-org:my-library:1.0.0:api"

    // Leaked to consumers of your library (requires java-library plugin)
    githubApi "my-org:my-library:1.0.0"

    // Compile classpath only — not included at runtime
    githubCompileOnly "my-org:annotation-processor:1.0.0"

    // Compile only, leaked to consumers (requires java-library plugin)
    githubCompileOnlyApi "my-org:annotations:1.0.0"

    // Runtime classpath only — not visible at compile time
    githubRuntimeOnly "my-org:jdbc-driver:1.0.0"
}

JAR selection

When no classifier is specified the plugin selects the best JAR from the release assets in this priority order:

1. repo.jar — exact name match
2. repo-VERSION.jar — versioned name match
3. repo-standalone.jar — standalone/fat JAR
4. First .jar that is not a -sources.jar or -javadoc.jar

Transitive GitHub dependencies

If a downloaded JAR contains a META-INF/github-dependencies.json file (written by this plugin's generateGithubDependencyMetadata task), those transitive GitHub dependencies are resolved and downloaded automatically. Cycles are prevented by a resolved-set guard.

Caching

Downloaded JARs are cached in ~/.gradle/github/OWNER/REPO-VERSION[-CLASSIFIER].jar. Re-running the build does not re-download them.