Publishing Releases

Publishing Releases

The publishGithub task builds your project and uploads one or more JARs as assets on a GitHub release.

How it works

1. Runs build (the task depends on it)
2. Resolves owner, repo, version, tag, and releaseName (from the extension or auto-detected)
3. Checks whether a release for the resolved tag already exists - if so, assets are uploaded to that existing release; if not, a new release is created
4. Uploads the configured JAR(s)

Configuration

Publishing is configured via the publishGithub { } extension, which can also be accessed nested inside github { publish { } }. Both paths configure the same object.

All fields

Field	Type	Default	Description
owner	String	auto-detected from git remote origin	GitHub user or organisation
repo	String	auto-detected from git remote origin	Repository name
version	String	project.version	Version string used for dependency resolution by consumers
tag	String	same as version	Git tag pushed to GitHub (e.g. "v1.0.0")
releaseName	String	same as tag	Human-readable release title shown on GitHub (e.g. "Release 1.0.0")
jar	File	auto-selected from build/libs/	Single JAR to upload (ignored when artifacts is non-empty)

Single-JAR (shorthand)

publishGithub {
    owner       = "my-org"
    repo        = "my-repo"
    version     = "1.0.0"
    tag         = "v1.0.0"
    releaseName = "Release 1.0.0"
    jar         = file("build/libs/my-lib.jar")
}

All fields are optional. With no configuration at all the plugin auto-detects everything:

// version must be set on the project
version = "1.0.0"
// owner/repo come from git remote origin
// tag = version, releaseName = tag
// jar = shadow/fat JAR or first .jar in build/libs/

Nested form (equivalent)

github {
    accessToken = "ghp_YOUR_TOKEN_HERE"

    publish {
        owner       = "my-org"
        repo        = "my-repo"
        version     = "1.0.0"
        tag         = "v1.0.0"
        releaseName = "Release 1.0.0"
        jar         = file("build/libs/my-lib.jar")
    }
}

Multi-JAR releases

Use the artifacts { } block to upload multiple JARs in a single release. Each artifact is identified by a classifier string that consumers use to select it.

publishGithub {
    version     = "1.0.0"
    tag         = "v1.0.0"
    releaseName = "Release 1.0.0"

    artifacts {
        artifact {
            classifier = ""       // default artifact - uploaded as my-repo.jar
            jar        = file("build/libs/my-lib.jar")
        }
        artifact {
            classifier = "api"    // uploaded as my-repo-api.jar
            jar        = file("build/libs/my-lib-api.jar")
        }
        artifact {
            classifier = "fat"    // uploaded as my-repo-fat.jar
            jar        = file("build/libs/my-lib-fat.jar")
        }
    }
}

Asset naming

Classifier	Asset file name
"" (empty / default)	repo.jar
"api"	repo-api.jar
"fat"	repo-fat.jar

Consumer side - selecting a classifier

dependencies {
    githubImplementation "my-org:my-repo:1.0.0"        // downloads my-repo.jar
    githubImplementation "my-org:my-repo:1.0.0:api"    // downloads my-repo-api.jar
    githubImplementation "my-org:my-repo:1.0.0:fat"    // downloads my-repo-fat.jar
}

JAR auto-selection (single-JAR mode)

When jar is not set and artifacts is empty, the plugin scans build/libs/ and picks:

1. A JAR whose name contains -standalone, -all, or -shadow (fat/shadow JAR)
2. Otherwise the first .jar that is not a -sources.jar or -javadoc.jar

Existing releases

If the release for the resolved tag already exists the task uploads assets to it rather than failing. This means re-running after a partial failure (e.g. a network drop mid-upload) is safe.

Running the task

gradle publishGithub

The task automatically runs build first, so you do not need to run gradle build publishGithub separately.