Publishing Java packages with Maven

In this tutorial, you'll learn how to use Maven to publish Java packages to a registry as part of your continuous integration (CI) workflow.

Dans cet article

Introduction

Ce guide vous montre comment créer un workflow qui publie des packages Java sur GitHub Packages et le dépôt central Maven. Avec un seul workflow, vous pouvez publier des packages sur un dépôt unique ou sur plusieurs dépôts.

Avertissement

Les exemples utilisés dans ce guide font référence au service OSSRH hérité. Consultez Publication dans la documentation du référentiel central Maven.

Prerequisites

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

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

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

About package configuration

The groupId and artifactId fields in the pom.xml file create a unique identifier for your package that registries use to link your package to a registry. For more information see Guide to uploading artifacts to the Central Repository in the Apache Maven documentation.

Avertissement

Votre package Apache Maven doit respecter la convention d’affectation de noms. Par conséquent, le champ artifactId ne doit contenir que des lettres minuscules, des chiffres ou des traits d’union. Pour plus d’informations, consultez Convention d’affectation de noms des coordonnées Maven dans la documentation maven.apache.org. Si vous utilisez des lettres majuscules dans le nom de l'artefact, vous obtiendrez 422 Entité non traitable en réponse.

The pom.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 the setup-java action to configure the deployment repository as well as authentication for that repository. For more information, see setup-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 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 Événements qui déclenchent des flux de travail.

In this workflow, you can use the setup-java action. This action installs the given version of the JDK into the PATH, but it also configures a Maven settings.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 in pom.xml, then you can specify that id during the setup-java action invocation.

For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, your pom.xml could specify a distribution management repository with the id of ossrh.

XML
<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 management id to the setup-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, see Using secrets in GitHub Actions.

YAML
name: Publish package to the Maven Central Repository
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - 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 }}

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 Maven settings.xml file to add authentication for the ossrh repository using the MAVEN_USERNAME and MAVEN_PASSWORD environment variables.

  3. Exécute la commande mvn --batch-mode deploy pour effectuer une publication sur le dépôt ossrh. La variable d’environnement MAVEN_USERNAME est définie avec le contenu de votre secret OSSRH_USERNAME, et la variable d’environnement MAVEN_PASSWORD est définie avec le contenu de votre secret OSSRH_TOKEN.

    For more information about using secrets in your workflow, see Using 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 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 Événements qui déclenchent des flux de travail.

In this workflow, you can use the setup-java action. This action installs the given version of the JDK into the PATH, and also sets up a Maven settings.xml for publishing the package to GitHub Packages. The generated settings.xml defines authentication for a server with an id of github, using the GITHUB_ACTOR environment variable as the username and the GITHUB_TOKEN environment variable as the password. The GITHUB_TOKEN environment variable is assigned the value of the special GITHUB_TOKEN secret.

Le secret GITHUB_TOKEN a la valeur d’un jeton d’accès pour le dépôt chaque fois qu’un travail d’un workflow démarre. Vous devez définir les autorisations de ce jeton d’accès dans le fichier de workflow afin d’octroyer l’accès en lecture pour l’autorisation contents et l’accès en écriture pour l’autorisation packages. Pour plus d’informations, consultez « Use GITHUB_TOKEN in workflows ».

For a Maven-based project, you can make use of these settings by creating a distribution repository in your pom.xml file with an id of github 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 in pom.xml would look similar to the below example.

XML
<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 generated settings.xml.

YAML
name: Publish package to GitHub Packages
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - 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 }}

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 Maven settings.xml file to add authentication for the github Maven repository to use the GITHUB_TOKEN environment variable.

  3. Exécute la commande mvn --batch-mode deploy pour publier sur GitHub Packages. La variable d’environnement GITHUB_TOKEN est définie avec le contenu du secret GITHUB_TOKEN. La clé permissions spécifie l’accès accordé au GITHUB_TOKEN.

    For more information about using secrets in your workflow, see Using 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 the setup-java action for each registry.

Ensure your pom.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 the id set to ossrh, and you might want to specify GitHub Packages in a distribution management repository with the id set to github.

YAML
name: Publish package to the Maven Central Repository and GitHub Packages
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - 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 }}

This workflow calls the setup-java action twice. Each time the setup-java action runs, it overwrites the Maven settings.xml file for publishing packages. For authentication to the repository, the settings.xml file references the distribution management repository id, and the username and password.

This workflow performs the following steps:

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

  2. Calls setup-java the first time. This configures the Maven settings.xml file for the ossrh repository, and sets the authentication options to environment variables that are defined in the next step.

  3. Exécute la commande mvn --batch-mode deploy pour effectuer une publication sur le dépôt ossrh. La variable d’environnement MAVEN_USERNAME est définie avec le contenu de votre secret OSSRH_USERNAME, et la variable d’environnement MAVEN_PASSWORD est définie avec le contenu de votre secret OSSRH_TOKEN.

  4. Calls setup-java the second time. This automatically configures the Maven settings.xml file for GitHub Packages.

  5. Exécute la commande mvn --batch-mode deploy pour publier sur GitHub Packages. La variable d’environnement GITHUB_TOKEN est définie avec le contenu du secret GITHUB_TOKEN. La clé permissions spécifie l’accès accordé au GITHUB_TOKEN.

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