Introduction

This guide shows you how to create a workflow that publishes Java packages to GitHub Packages and the Maven Central Repository. With a single workflow, you can publish packages to a single repository or to multiple repositories.

Prerequisites

We recommend that you have a basic understanding of workflow files and configuration options. For more information, seeWriting workflows.

For more information about creating a CI workflow for your Java project with Maven, seeBuilding and testing Java with Maven.

You may also find it helpful to have a basic understanding of the following:

• Working with the Apache Maven registry
• Store information in variables
• Using secrets in GitHub Actions
• Use GITHUB_TOKEN for authentication in workflows

About package configuration

ThegroupId andartifactId fields in thepom.xml file create a unique identifier for your package that registries use to link your package to a registry. For more information seeGuide to uploading artifacts to the Central Repository in the Apache Maven documentation.

Thepom.xml file also contains configuration for the distribution management repositories that Maven will deploy packages to. Each repository must have a name and a deployment URL. Authentication for these repositories can be configured in the.m2/settings.xml file in the home directory of the user running Maven.

You can use thesetup-java action to configure the deployment repository as well as authentication for that repository. For more information, seesetup-java.

Publishing packages to the Maven Central Repository

Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when therelease event triggers with typecreated. The workflow publishes the package to the Maven Central Repository if CI tests pass. For more information on therelease event, seeEvents that trigger workflows.

In this workflow, you can use thesetup-java action. This action installs the given version of the JDK into thePATH, but it also configures a Mavensettings.xml for publishing packages. By default, the settings file will be configured for GitHub Packages, but it can be configured to deploy to another package registry, such as the Maven Central Repository. If you already have a distribution management repository configured inpom.xml, then you can specify thatid during thesetup-java action invocation.

For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, yourpom.xml could specify a distribution management repository with theid ofossrh.

<project ...>  ...  <distributionManagement>    <repository>      <id>ossrh</id>      <name>Central Repository OSSRH</name>      <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>    </repository>  </distributionManagement></project>

<project...>  ...<distributionManagement><repository><id>ossrh</id><name>Central Repository OSSRH</name><url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url></repository></distributionManagement></project>

With this configuration, you can create a workflow that publishes your package to the Maven Central Repository by specifying the repository managementid to thesetup-java action. You’ll also need to provide environment variables that contain the username and password to authenticate to the repository.

In the deploy step, you’ll need to set the environment variables to the username that you authenticate with to the repository, and to a secret that you’ve configured with the password or token to authenticate with. For more information, seeUsing secrets in GitHub Actions.

name: Publish package to the Maven Central Repositoryon:  release:    types: [created]jobs:  publish:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v5      - name: Set up Maven Central Repository        uses: actions/setup-java@v4        with:          java-version: '11'          distribution: 'temurin'          server-id: ossrh          server-username: MAVEN_USERNAME          server-password: MAVEN_PASSWORD      - name: Publish package        run: mvn --batch-mode deploy        env:          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}

name:PublishpackagetotheMavenCentralRepositoryon:release:types: [created]jobs:publish:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:SetupMavenCentralRepositoryuses:actions/setup-java@v4with:java-version:'11'distribution:'temurin'server-id:ossrhserver-username:MAVEN_USERNAMEserver-password:MAVEN_PASSWORD-name:Publishpackagerun:mvn--batch-modedeployenv:MAVEN_USERNAME:${{secrets.OSSRH_USERNAME}}MAVEN_PASSWORD:${{secrets.OSSRH_TOKEN}}

This workflow performs the following steps:

1. Checks out a copy of project's repository.

2. Sets up the Java JDK, and also configures the Mavensettings.xml file to add authentication for theossrh repository using theMAVEN_USERNAME andMAVEN_PASSWORD environment variables.

3. Runs themvn --batch-mode deploy command to publish to theossrh repository. TheMAVEN_USERNAME environment variable will be set with the contents of yourOSSRH_USERNAME secret, and theMAVEN_PASSWORD environment variable will be set with the contents of yourOSSRH_TOKEN secret.

   For more information about using secrets in your workflow, seeUsing secrets in GitHub Actions.

Publishing packages to GitHub Packages

Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when therelease event triggers with typecreated. The workflow publishes the package to GitHub Packages if CI tests pass. For more information on therelease event, seeEvents that trigger workflows.

In this workflow, you can use thesetup-java action. This action installs the given version of the JDK into thePATH, and also sets up a Mavensettings.xml for publishing the package to GitHub Packages. The generatedsettings.xml defines authentication for a server with anid ofgithub, using theGITHUB_ACTOR environment variable as the username and theGITHUB_TOKEN environment variable as the password. TheGITHUB_TOKEN environment variable is assigned the value of the specialGITHUB_TOKEN secret.

TheGITHUB_TOKEN secret is set to an access token for the repository each time a job in a workflow begins. You should set the permissions for this access token in the workflow file to grant read access for thecontents permission and write access for thepackages permission. For more information, seeUse GITHUB_TOKEN for authentication in workflows.

For a Maven-based project, you can make use of these settings by creating a distribution repository in yourpom.xml file with anid ofgithub that points to your GitHub Packages endpoint.

For example, if your organization is named "octocat" and your repository is named "hello-world", then the GitHub Packages configuration inpom.xml would look similar to the below example.

<project ...>  ...  <distributionManagement>    <repository>      <id>github</id>      <name>GitHub Packages</name>      <url>https://maven.pkg.github.com/octocat/hello-world</url>    </repository>  </distributionManagement></project>

<project...>  ...<distributionManagement><repository><id>github</id><name>GitHub Packages</name><url>https://maven.pkg.github.com/octocat/hello-world</url></repository></distributionManagement></project>

With this configuration, you can create a workflow that publishes your package to GitHub Packages by making use of the automatically generatedsettings.xml.

name: Publish package to GitHub Packageson:  release:    types: [created]jobs:  publish:    runs-on: ubuntu-latest    permissions:      contents: read      packages: write    steps:      - uses: actions/checkout@v5      - uses: actions/setup-java@v4        with:          java-version: '11'          distribution: 'temurin'      - name: Publish package        run: mvn --batch-mode deploy        env:          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name:PublishpackagetoGitHubPackageson:release:types: [created]jobs:publish:runs-on:ubuntu-latestpermissions:contents:readpackages:writesteps:-uses:actions/checkout@v5-uses:actions/setup-java@v4with:java-version:'11'distribution:'temurin'-name:Publishpackagerun:mvn--batch-modedeployenv:GITHUB_TOKEN:${{secrets.GITHUB_TOKEN}}

This workflow performs the following steps:

1. Checks out a copy of project's repository.

2. Sets up the Java JDK, and also automatically configures the Mavensettings.xml file to add authentication for thegithub Maven repository to use theGITHUB_TOKEN environment variable.

3. Runs themvn --batch-mode deploy command to publish to GitHub Packages. TheGITHUB_TOKEN environment variable will be set with the contents of theGITHUB_TOKEN secret. Thepermissions key specifies the access granted to theGITHUB_TOKEN.

   For more information about using secrets in your workflow, seeUsing secrets in GitHub Actions.

Publishing packages to the Maven Central Repository and GitHub Packages

You can publish your packages to both the Maven Central Repository and GitHub Packages by using thesetup-java action for each registry.

Ensure yourpom.xml file includes a distribution management repository for both your GitHub repository and your Maven Central Repository provider. For example, if you deploy to the Central Repository through the OSSRH hosting project, you might want to specify it in a distribution management repository with theid set toossrh, and you might want to specify GitHub Packages in a distribution management repository with theid set togithub.

name: Publish package to the Maven Central Repository and GitHub Packageson:  release:    types: [created]jobs:  publish:    runs-on: ubuntu-latest    permissions:      contents: read      packages: write    steps:      - uses: actions/checkout@v5      - name: Set up Java for publishing to Maven Central Repository        uses: actions/setup-java@v4        with:          java-version: '11'          distribution: 'temurin'          server-id: ossrh          server-username: MAVEN_USERNAME          server-password: MAVEN_PASSWORD      - name: Publish to the Maven Central Repository        run: mvn --batch-mode deploy        env:          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}      - name: Set up Java for publishing to GitHub Packages        uses: actions/setup-java@v4        with:          java-version: '11'          distribution: 'temurin'      - name: Publish to GitHub Packages        run: mvn --batch-mode deploy        env:          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name:PublishpackagetotheMavenCentralRepositoryandGitHubPackageson:release:types: [created]jobs:publish:runs-on:ubuntu-latestpermissions:contents:readpackages:writesteps:-uses:actions/checkout@v5-name:SetupJavaforpublishingtoMavenCentralRepositoryuses:actions/setup-java@v4with:java-version:'11'distribution:'temurin'server-id:ossrhserver-username:MAVEN_USERNAMEserver-password:MAVEN_PASSWORD-name:PublishtotheMavenCentralRepositoryrun:mvn--batch-modedeployenv:MAVEN_USERNAME:${{secrets.OSSRH_USERNAME}}MAVEN_PASSWORD:${{secrets.OSSRH_TOKEN}}-name:SetupJavaforpublishingtoGitHubPackagesuses:actions/setup-java@v4with:java-version:'11'distribution:'temurin'-name:PublishtoGitHubPackagesrun:mvn--batch-modedeployenv:GITHUB_TOKEN:${{secrets.GITHUB_TOKEN}}

This workflow calls thesetup-java action twice. Each time thesetup-java action runs, it overwrites the Mavensettings.xml file for publishing packages. For authentication to the repository, thesettings.xml file references the distribution management repositoryid, and the username and password.

This workflow performs the following steps:

1. Checks out a copy of project's repository.

2. Callssetup-java the first time. This configures the Mavensettings.xml file for theossrh repository, and sets the authentication options to environment variables that are defined in the next step.

3. Runs themvn --batch-mode deploy command to publish to theossrh repository. TheMAVEN_USERNAME environment variable will be set with the contents of yourOSSRH_USERNAME secret, and theMAVEN_PASSWORD environment variable will be set with the contents of yourOSSRH_TOKEN secret.

4. Callssetup-java the second time. This automatically configures the Mavensettings.xml file for GitHub Packages.

5. Runs themvn --batch-mode deploy command to publish to GitHub Packages. TheGITHUB_TOKEN environment variable will be set with the contents of theGITHUB_TOKEN secret. Thepermissions key specifies the access granted to theGITHUB_TOKEN.

   For more information about using secrets in your workflow, seeUsing secrets in GitHub Actions.