Configuring Gradle for use with GitHub Package Registry

You can publish an Apache Maven package using Gradle to GitHub Package Registry and use the package as a dependency in a Java project.

GitHub Package Registry is currently available in limited public beta. You should avoid using GitHub Package Registry for high-value workflows and content during the beta period. For more information, see "About GitHub Package Registry."

In this article

Authenticating to GitHub Package Registry

You must use a personal access token with the read:packages and write:packages scopes to publish and delete public packages in the GitHub Package Registry with Apache Maven. Your personal access token must also have the repo scope when the repository is private. For more information, see "Creating a personal access token for the command line."

If you're using Gradle Groovy, configure Gradle to use your token when pushing new packages by editing your build.gradle file, or creating a file if the file doesn't exist. The file should look similar to the example below. Replace OWNER with the GitHub user or organization name that contains the repository you will be publishing the package to or installing packages from and REPOSITORY with the name of the GitHub repository.

Use this example for a single package.

plugins {
    id("maven-publish")
}

publishing {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/OWNER/REPOSITORY")
            credentials {
                username = project.findProperty("gpr.user") ?: System.getenv("GPR_USER")
                password = project.findProperty("gpr.key") ?: System.getenv("GPR_API_KEY")
            }
        }
    }
    publications {
        gpr(MavenPublication) {
            from(components.java)
        }
    }
}

Use this example for multiple packages in the same repository.

plugins {
    id("maven-publish") apply false
}

subprojects {
    apply plugin: "maven-publish"
    publishing {
        repositories {
            maven {
                name = "GitHubPackages"
                url = uri("https://maven.pkg.github.com/OWNER/REPOSITORY")
                credentials {
                    username = project.findProperty("gpr.user") ?: System.getenv("GPR_USER")
                    password = project.findProperty("gpr.key") ?: System.getenv("GPR_API_KEY")
                }
            }
        }
        publications {
            gpr(MavenPublication) {
                from(components.java)
            }
        }
    }
}

If you're using Kotlin DSL, configure Gradle to use your token when pushing new packages by editing your build.gradle.kts file, or creating a file if the file doesn't exist. Replace OWNER with the GitHub user or organization name that contains the repository you will be publishing the package to or installing packages from and REPOSITORY with the name of the GitHub repository.

Use this example for a single package.

plugins {
    `maven-publish`
}

publishing {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/OWNER/REPOSITORY")
            credentials {
                username = project.findProperty("gpr.user") as String? ?: System.getenv("GPR_USER")
                password = project.findProperty("gpr.key") as String? ?: System.getenv("GPR_API_KEY")
            }
        }
    }
    publications {
        register("gpr") {
            from(components["java"])
        }
    }
}

Use this example for multiple packages in the same repository.

plugins {
    `maven-publish` apply false
}

subprojects {
    apply(plugin = "maven-publish")
    configure {
        repositories {
            maven {
                name = "GitHubPackages"
                url = uri("https://maven.pkg.github.com/OWNER/REPOSITORY")
                credentials {
                    username = project.findProperty("gpr.user") as String? ?: System.getenv("GPR_USER")
                    password = project.findProperty("gpr.key") as String? ?: System.getenv("GPR_API_KEY")
                }
            }
        }
        publications {
            register("gpr") {
                from(components["java"])
            }
        }
    }
}

If you are using a GitHub Actions workflow, you can use a GITHUB_TOKEN to publish and consume packages in the GitHub Package Registry without needing to store and manage a personal access token. For more information about GITHUB_TOKEN, see "GITHUB_TOKEN secret."

You can use a script to inject your GITHUB_TOKEN into the appropriate configuration file for GitHub Package Registry. Add GitHub Package Registry as an alternative registry or repository in the configuration file for the package client, as well as your GitHub username and a personal access token with the appropriate scopes. The exact steps for creating a configuration file vary by package type.

Publishing a package

When you push, by default the package is created in a repository with the same name as your package name. For example, a package named com.example.test would be published to the OWNER/test GitHub Package Registry repository.

  1. Set up Gradle to authenticate to GitHub Package Registry by editing your build.gradle or build.gradle.kts file. For more information, see "Authenticating to GitHub Package Registry."

  2. After you've created your package and are ready to publish it to your GitHub Package Registry user or organization, publish the package.

    $ gradle publish
  3. You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

    https://github.com/OWNER/REPOSITORY/packages

Receiving package registry events

You can receive webhook events when a package is published or updated. For more information, see "RegistryPackageEvent" in the GitHub Developer documentation.

Installing a package

  1. Set up Gradle to authenticate to GitHub Package Registry by editing your build.gradle or build.gradle.kts file. For more information, see "Authenticating to GitHub Package Registry".

  2. Add the package dependencies to your build.gradle or build.gradle.kts file.

    Use this example for Grady Groovy.

    dependencies {
        implementation 'com.example:package'
    }

    Use this example for Kotlin DSL.

    dependencies {
        implementation("com.example:package")
    }

    For more information, see "Declaring dependencies" in the Gradle documentation.

  3. Install the package.

    $ gradle install

Deleting a package

To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support deleting published versions of a package or an entire published package for public repositories. Under special circumstances, such as for legal reasons or to conform with GDPR standards, you can request deleting a package through GitHub Support. Contact GitHub Support using our contact form and the subject line "GitHub Package Registry."

You can delete private packages via GitHub's API. For more information, see "Access to package version deletion" in the GitHub Developer documentation.

Further reading

Ask a human

Can't find what you're looking for?

Contact us