Configuring Apache Maven for use with GitHub Package Registry
You can publish an Apache Maven package to GitHub Package Registry and use it 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
- Publishing a package
- Receiving package registry events
- Installing a package
- Deleting a package
Authenticating to GitHub Package Registry
You must use a personal access token with the
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."
You can also use a
GITHUB_TOKEN to push packages to the GitHub Package Registry in a GitHub Actions workflow. For more information, see "`GITHUB_TOKEN secret."
Configure Apache Maven to use your token when pushing new packages by editing your
~/.m2/settings.xml file, or creating one it if it doesn't exist. The file should look similar to the example below. Replace
USERNAME with your GitHub username,
TOKEN with your personal access token, and
OWNER with the GitHub user or organization name that contains the repository you will be publishing the package to or installing packages from.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <activeProfiles> <activeProfile>github</activeProfile> </activeProfiles> <profiles> <profile> <id>github</id> <repositories> <repository> <id>central</id> <url>https://repo1.maven.org/maven2</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>true</enabled></snapshots> </repository> <repository> <id>github</id> <name>GitHub OWNER Apache Maven Packages</name> <url>https://maven.pkg.github.com/OWNER</url> </repository> </repositories> </profile> </profiles> <servers> <server> <id>github</id> <username>USERNAME</username> <password>TOKEN</password> </server> </servers> </settings>
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. A GitHub Package Registry release and associated Git tag will be automatically created for the version of the package, if it doesn't already exist.
If you would like to publish multiple packages to the same repository, you can include the URL to the GitHub Package Registry repository in the
<scm> section of
pom.xml. GitHub Package Registry will match the repository based on that field.
For more information on creating your package, see the maven.apache.org documentation.
Since the repository name is part of the distributionManagement section, there are no additional steps to publish multiple packages to the same repository.
pom.xmlfile located in your package directory. It should look similar to the example below. Replace
<url>with the GitHub Package Registry user or organization name that contains the repository you will be publishing the package to or installing packages from. Replace
REPOSITORYwith the name of the repository:
<distributionManagement> <repository> <id>github</id> <name>GitHub OWNER Apache Maven Packages</name> <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url> </repository> </distributionManagement>
After you've created your package and are ready to publish it to your GitHub Package Registry user or organization, run:
$ mvn deploy
You can access your packages from this URL by replacing
OWNERwith your GitHub user or organization name and
REPOSITORYwith your repository name:
Receiving package registry events
You can receive webhook events when a package is
updated. For more information, see "RegistryPackageEvent" in the GitHub Developer documentation.
Installing a package
Set up Apache Maven to authenticate to GitHub Package Registry by editing your
~/.m2/settings.xml. For more information, see "Authenticating to GitHub Package Registry".
Add the package dependencies to your
pom.xml. For example this
dependenciesnode of a
<dependencies> <dependency> <groupId>com.example</groupId> <artifactId>test</artifactId> <version>1.0.0</version> </dependency> </dependencies>
Install the package.
$ mvn install
For more information on using a
pom.xml in your project, see "Introduction to the POM" in the Apache Maven documentation.
Deleting a package
To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support package deletion or deleting a version of a package. 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."