Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.
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, see "Learn GitHub Actions."
For more information about creating a CI workflow for your Java project with Gradle, see "Building and testing Java with Gradle."
You may also find it helpful to have a basic understanding of the following:
- "Working with the npm registry"
- "Environment variables"
- "Encrypted secrets"
- "Authentication in a workflow"
About package configuration
The groupId
and artifactId
fields in the MavenPublication
section of the build.gradle file create a unique identifier for your package that registries use to link your package to a registry. This is similar to the groupId
and artifactId
fields of the Maven pom.xml file. For more information, see the "Maven Publish Plugin" in the Gradle documentation.
The build.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 the release
event triggers with type created
. The workflow publishes the package to the Maven Central Repository if CI tests pass. For more information on the release
event, see "Events that trigger workflows."
You can define a new Maven repository in the publishing block of your build.gradle file that points to your package repository. For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, your build.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")
}
}
}
}
With this configuration, you can create a workflow that publishes your package to the Maven Central Repository by running the gradle 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, see "Creating and using encrypted secrets."
# 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.
name: Publish package to the Maven Central Repository
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Java
uses: actions/setup-java@v2
with:
java-version: '11'
distribution: 'adopt'
- name: Validate Gradle wrapper
uses: gradle/wrapper-validation-action@e6e38bacfdf1a337459f332974bb2327a31aaf4b
- name: Publish package
uses: gradle/gradle-build-action@937999e9cc2425eddc7fd62d1053baf041147db7
with:
arguments: publish
env:
MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
This workflow performs the following steps:
-
Checks out a copy of project's repository.
-
Sets up the Java JDK.
-
Validates the checksums of any Gradle Wrapper JAR files present in the repository.
-
Runs the
gradle/gradle-build-action
action with thepublish
argument 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, see "Creating and using encrypted secrets."
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 the release
event triggers with type created
. The workflow publishes the package to GitHub Packages if CI tests pass. For more information on the release
event, see "Events that trigger workflows."
You can define a new Maven repository in the publishing block of your build.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 the GITHUB_ACTOR
environment variable as a username, and you can set the GITHUB_TOKEN
environment variable with your GITHUB_TOKEN
secret.
The GITHUB_TOKEN
secret is set to an access token for the repository each time a job in a workflow begins. It has read and write permissions for packages in the repository where the workflow runs. For more information, see "Authenticating with the GITHUB_TOKEN."
For example, if your organization is named "octocat" and your repository is named "hello-world", then the GitHub Packages configuration in build.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")
}
}
}
}
With this configuration, you can create a workflow that publishes your package to GitHub Packages by running the gradle 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.
name: Publish package to GitHub Packages
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-java@v2
with:
java-version: '11'
distribution: 'adopt'
- name: Validate Gradle wrapper
uses: gradle/wrapper-validation-action@e6e38bacfdf1a337459f332974bb2327a31aaf4b
- name: Publish package
uses: gradle/gradle-build-action@937999e9cc2425eddc7fd62d1053baf041147db7
with:
arguments: publish
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
This workflow performs the following steps:
-
Checks out a copy of project's repository.
-
Sets up the Java JDK.
-
Validates the checksums of any Gradle Wrapper JAR files present in the repository.
-
Runs the
gradle/gradle-build-action
action with thepublish
argument to publish to GitHub Packages. TheGITHUB_TOKEN
environment variable will be set with the content of theGITHUB_TOKEN
secret.For more information about using secrets in your workflow, see "Creating and using encrypted secrets."
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 your build.gradle file.
Ensure your build.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 the name
set to OSSRH
. If you deploy to GitHub Packages, you might want to specify it in a distribution management repository with the name
set to GitHubPackages
.
If your organization is named "octocat" and your repository is named "hello-world", then the configuration in build.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")
}
}
}
}
With this configuration, you can create a workflow that publishes your package to both the Maven Central Repository and GitHub Packages by running the gradle 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.
name: Publish package to the Maven Central Repository and GitHub Packages
on:
release:
types: [created]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Java
uses: actions/setup-java@v2
with:
java-version: '11'
distribution: 'adopt'
- name: Validate Gradle wrapper
uses: gradle/wrapper-validation-action@e6e38bacfdf1a337459f332974bb2327a31aaf4b
- name: Publish package
uses: gradle/gradle-build-action@937999e9cc2425eddc7fd62d1053baf041147db7
with:
arguments: publish
env:
MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
This workflow performs the following steps:
-
Checks out a copy of project's repository.
-
Sets up the Java JDK.
-
Validates the checksums of any Gradle Wrapper JAR files present in the repository.
-
Runs the
gradle/gradle-build-action
action with thepublish
argument 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.For more information about using secrets in your workflow, see "Creating and using encrypted secrets."