Configuring Apache Maven for use with 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 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."

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.

1. Edit the pom.xml file located in your package directory. It should look similar to the example below. Replace OWNER in the <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:

   <distributionManagement>
      <repository>
        <id>github</id>
        <name>GitHub OWNER Apache Maven Packages</name>
        <url>https://maven.pkg.github.com/OWNER</url>
      </repository>
   </distributionManagement>
   

2. If you'd like to publish multiple packages to the same repository, specify the URL of the GitHub Package Registry repository where you want to publish them in the <scm> section of the pom.xml file. It should look similar to the example below. Replace OWNER with the GitHub Package Registry user or organization name and REPOSITORY with the name of the repository:

   <scm>
     <connection>scm:git:https://github.com/OWNER/REPOSITORY.git</connection>
     <developerConnection>scm:git:https://github.com/OWNER/REPOSITORY.git</developerConnection>
     <url>https://github.com/OWNER/REPOSITORY</url>
   </scm>
   

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

   $ mvn deploy

4. 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 Apache Maven to authenticate to GitHub Package Registry by editing your ~/.m2/settings.xml. For more information, see "Authenticating to GitHub Package Registry".

2. Add the package dependencies to your pom.xml. For example this dependencies node of a pom.xml uses the com.example.test package:

   <dependencies>
     <dependency>
       <groupId>com.example</groupId>
       <artifactId>test</artifactId>
       <version>1.0.0</version>
     </dependency>
   </dependencies>
   

3. 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 unpublish a package, run this command to delete the package version from GitHub Package Registry.

$ curl -H "Authorization: Bearer TOKEN" -X DELETE \
 https://maven.pkg.github.com/OWNER/com/example/PACKAGE NAME/VERSION