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 Gradle, seeBuilding and testing Java with Gradle.

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 theMavenPublication section of thebuild.gradle file create a unique identifier for your package that registries use to link your package to a registry. This is similar to thegroupId andartifactId fields of the Mavenpom.xml file. For more information, see theMaven Publish Plugin in the Gradle documentation.

Thebuild.gradle file also contains configuration for the distribution management repositories that Gradle will publish packages to. Each repository must have a name, a deployment URL, and credentials for authentication.

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.

You can define a new Maven repository in the publishing block of yourbuild.gradle file that points to your package repository. For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, yourbuild.gradle could specify a repository with the name"OSSRH".

plugins {  ...  id 'maven-publish'}publishing {  ...  repositories {    maven {      name = "OSSRH"      url = "https://oss.sonatype.org/service/local/staging/deploy/maven2/"      credentials {        username = System.getenv("MAVEN_USERNAME")        password = System.getenv("MAVEN_PASSWORD")      }    }  }}

plugins {  ...  id'maven-publish'}publishing {  ...  repositories {    maven {      name ="OSSRH"      url ="https://oss.sonatype.org/service/local/staging/deploy/maven2/"      credentials {        username = System.getenv("MAVEN_USERNAME")        password = System.getenv("MAVEN_PASSWORD")      }    }  }}

With this configuration, you can create a workflow that publishes your package to the Maven Central Repository by running thegradle publish command. In the deploy step, you’ll need to set environment variables for the username and password or token that you use to authenticate to the Maven repository. For more information, seeUsing secrets in GitHub Actions.

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.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 Java        uses: actions/setup-java@v4        with:          java-version: '11'          distribution: 'temurin'      - name: Setup Gradle        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2      - name: Publish package        run: ./gradlew publish        env:          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.name:PublishpackagetotheMavenCentralRepositoryon:release:types: [created]jobs:publish:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:SetupJavauses:actions/setup-java@v4with:java-version:'11'distribution:'temurin'-name:SetupGradleuses:gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3# v4.4.2-name:Publishpackagerun:./gradlewpublishenv: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.

3. Sets up the Gradle environment. Thegradle/actions/setup-gradle action takes care of caching state between workflow runs, and provides a detailed summary of all Gradle executions.

4. Executes the Gradlepublish task to publish to theOSSRH Maven 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.

You can define a new Maven repository in the publishing block of yourbuild.gradle that points to GitHub Packages. In that repository configuration, you can also take advantage of environment variables set in your CI workflow run. You can use theGITHUB_ACTOR environment variable as a username, and you can set theGITHUB_TOKEN environment variable with yourGITHUB_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 example, if your organization is named "octocat" and your repository is named "hello-world", then the GitHub Packages configuration inbuild.gradle would look similar to the below example.

plugins {  ...  id 'maven-publish'}publishing {  ...  repositories {    maven {      name = "GitHubPackages"      url = "https://maven.pkg.github.com/octocat/hello-world"      credentials {        username = System.getenv("GITHUB_ACTOR")        password = System.getenv("GITHUB_TOKEN")      }    }  }}

plugins {  ...  id'maven-publish'}publishing {  ...  repositories {    maven {      name ="GitHubPackages"      url ="https://maven.pkg.github.com/octocat/hello-world"      credentials {        username = System.getenv("GITHUB_ACTOR")        password = System.getenv("GITHUB_TOKEN")      }    }  }}

With this configuration, you can create a workflow that publishes your package to GitHub Packages by running thegradle publish command.

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.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: Setup Gradle        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2      - name: Publish package        run: ./gradlew publish        env:          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.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:SetupGradleuses:gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3# v4.4.2-name:Publishpackagerun:./gradlewpublishenv: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.

3. Sets up the Gradle environment. Thegradle/actions/setup-gradle action takes care of caching state between workflow runs, and provides a detailed summary of all Gradle executions.

4. Executes the Gradlepublish task to publish to GitHub Packages. TheGITHUB_TOKEN environment variable will be set with the content of theGITHUB_TOKEN secret. Thepermissions key specifies the access that theGITHUB_TOKEN secret will allow.

   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 configuring each in yourbuild.gradle file.

Ensure yourbuild.gradle file includes a 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 thename set toOSSRH. If you deploy to GitHub Packages, you might want to specify it in a distribution management repository with thename set toGitHubPackages.

If your organization is named "octocat" and your repository is named "hello-world", then the configuration inbuild.gradle would look similar to the below example.

plugins {  ...  id 'maven-publish'}publishing {  ...  repositories {    maven {      name = "OSSRH"      url = "https://oss.sonatype.org/service/local/staging/deploy/maven2/"      credentials {        username = System.getenv("MAVEN_USERNAME")        password = System.getenv("MAVEN_PASSWORD")      }    }    maven {      name = "GitHubPackages"      url = "https://maven.pkg.github.com/octocat/hello-world"      credentials {        username = System.getenv("GITHUB_ACTOR")        password = System.getenv("GITHUB_TOKEN")      }    }  }}

plugins {  ...  id'maven-publish'}publishing {  ...  repositories {    maven {      name ="OSSRH"      url ="https://oss.sonatype.org/service/local/staging/deploy/maven2/"      credentials {        username = System.getenv("MAVEN_USERNAME")        password = System.getenv("MAVEN_PASSWORD")      }    }    maven {      name ="GitHubPackages"      url ="https://maven.pkg.github.com/octocat/hello-world"      credentials {        username = System.getenv("GITHUB_ACTOR")        password = System.getenv("GITHUB_TOKEN")      }    }  }}

With this configuration, you can create a workflow that publishes your package to both the Maven Central Repository and GitHub Packages by running thegradle publish command.

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.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        uses: actions/setup-java@v4        with:          java-version: '11'          distribution: 'temurin'      - name: Setup Gradle        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2      - name: Publish package        run: ./gradlew publish        env:           MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.# GitHub recommends pinning actions to a commit SHA.# To get a newer version, you will need to update the SHA.# You can also reference a tag or branch, but the action may change without warning.name:PublishpackagetotheMavenCentralRepositoryandGitHubPackageson:release:types: [created]jobs:publish:runs-on:ubuntu-latestpermissions:contents:readpackages:writesteps:-uses:actions/checkout@v5-name:SetupJavauses:actions/setup-java@v4with:java-version:'11'distribution:'temurin'-name:SetupGradleuses:gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3# v4.4.2-name:Publishpackagerun:./gradlewpublishenv:MAVEN_USERNAME:${{secrets.OSSRH_USERNAME}}MAVEN_PASSWORD:${{secrets.OSSRH_TOKEN}}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.

3. Sets up the Gradle environment. Thegradle/actions/setup-gradle action takes care of caching state between workflow runs, and provides a detailed summary of all Gradle executions.

4. Executes the Gradlepublish task to publish to theOSSRH Maven repository and GitHub Packages. 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. TheGITHUB_TOKEN environment variable will be set with the content of theGITHUB_TOKEN secret. Thepermissions key specifies the access that theGITHUB_TOKEN secret will allow.

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