Publish Maven Package on GitHub Packages with GitHub Actions

Whether for private tinkering projects or public libraries: it often makes sense to store the packages in a Maven repository. For those who already use GitHub, the GitHub Package Repository comes in very handy. However, there are a few things to bear in mind here.

Prepare pom.xml

Before we take care of the GitHub workflow, we first need to customise our pom.xml and configure the distributionManagement options there, which is just inside the project tag.

<distributionManagement>
    <repository>
        <id>github</id>
        <name>Projekt Name</name>
        <url>https://maven.pkg.github.com/tinyoverflow/project-name</url>
    </repository>
</distributionManagement>

Create GitHub Workflow

Now the project is prepared and we can turn our attention to the GitHub workflow file. The following workflow works as follows:

1. The workflow is triggered by pushing tags in the format *.*.
2. On an Ubuntu machine, it is executed:
   1. Retrieve the source code from the repository.
   2. Install and configure Java, including cache. The server-id is identical to the ID from the pom.xml
   3. The project is compiled using Maven.
   4. The project is built and uploaded to the package repository using the configuration in the pom.xml.

name: Build and Publish

on:
  push:
    tags: [ "*.*" ]

jobs:
  build:
    name: Build and Publish
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: "17"
          distribution: 'temurin'
          cache: maven
          server-id: github
          settings-path: ${{ github.workspace }}

      - name: Build with Maven
        run: mvn -B package --file pom.xml

      - name: Publish to GitHub Packages Apache Maven
        run: mvn --batch-mode deploy -s $GITHUB_WORKSPACE/settings.xml
        if: startsWith(github.ref, 'refs/tags/')
        env:
          GITHUB_TOKEN: ${{ github.token }}

More detailed information about the workflow file can be found in the GitHub Actions documentation.

Troubleshooting

Sometimes problems occur that are not self-explanatory at first glance. In the following I will go into some of these possible errors.

Workflow fails with 403 Unauthorised

This error can have the following causes, among others:

1. The workflow token does not have the required permissions
   1. Go to the settings of your repository to Code and automation -> Actions -> General.
   2. At the bottom of the page you will find the option Workflow permissions.
   3. Make sure that the option Read and write permissions is selected.
2. The repository URL in the pom.xml is wrong
   Make sure that the repository URL in your pom.yml is correct. It starts with https://maven.pkg.github.com/ instead of https://github.com/.
   Example: https://maven.pkg.github.com/tinyoverflow/project-name

Workflow fails with 422 Unprocessable Entity

If this error occurs, the artifactId in your pom.xml is probably invalid. In order for you to upload an artefact to the GitHub package repository, it must only consist of lowercase letters, numbers and hyphens.

<!-- Correct -->
<groupId>me.tinyoverflow</groupId>
<artifactId>project-name</artifactId>
<version>1.0.0-SNAPSHOT</version>

<!-- Incorrect -->
<groupId>me.tinyoverflow</groupId>
<artifactId>ProjectName</artifactId>
<version>1.0.0-SNAPSHOT</version>

Please do not forget to adjust any scripts when changing your artifactId as this may affect the final filename.