Using GitHub Packages with Maven within the OpenMRS eco-system

This comprehensive guide provides a step-by-step process for configuring and using GitHub Packages to host and manage Maven artifacts within your OpenMRS Distribution.

GitHub Packages offers a secure and streamlined method for containerizing software packages, allowing them to be shared and managed alongside source code in repositories, facilitating collaboration and continuous integration.

Prerequisites

Before you begin, ensure you have:

GitHub Account
GitHub Personal Access Token (PAT)
Maven Installation

Understanding GitHub Packages

GitHub Packages is a comprehensive package registry service that allows OpenMRS developers and organizations to deploy, manage, and distribute their Maven artifacts.

When working with OpenMRS distributions, GitHub Packages serves as a crucial component in the dependency management ecosystem. It enables teams to host private or organization specific modules that aren't deployed on maven.

The package structure in GitHub Packages follows Maven's standard conventions, where each package is identified by its group ID, artifact ID, and version. For OpenMRS modules, the group ID` typically follows the pattern org.openmrs.module, while the artifact ID represents the specific module name.

Setting Up Authentication

1. Create GitHub Personal Access Token

Go to GitHub Settings → Developer Settings → Personal Access Tokens
Click "Generate new token"
Select required scopes:
- read:packages for downloading packages
- write:packages for publishing packages
Copy the generated token immediately

2. Configure Maven Settings

Create or edit ~/.m2/settings.xml:

<settings xmlns="<http://maven.apache.org/SETTINGS/1.0.0>"
  xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
  xsi:schemaLocation="<http://maven.apache.org/SETTINGS/1.0.0>
                      <http://maven.apache.org/xsd/settings-1.0.0.xsd>">

  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
        </repository>
        <repository>
          <id>github</id>
          <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github</id>
      <username>YOUR_GITHUB_USERNAME</username>
      <password>YOUR_GITHUB_TOKEN</password>
    </server>
  </servers>
</settings>

Use environment variables to replace the following with actual useable values.

OWNER: GitHub organization or username
REPOSITORY: Repository name
YOUR_GITHUB_USERNAME: Your GitHub username
YOUR_GITHUB_TOKEN: Your GitHub Personal Access Token

Configuring Maven

1. Project Configuration

Add the GitHub Packages repository to your module's pom.xml:

<repositories>
  <repository>
    <id>github</id>
    <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

2. Dependency Management

Add dependencies to your pom.xml:

<dependencies>
  <dependency>
    <groupId>org.openmrs.module</groupId>
    <artifactId>test</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </dependency>
</dependencies>

Using Packages in Your Project

1. Installing Dependencies

Run Maven install to download dependencies:

mvn clean install

2. Publishing Packages

To publish a package:

Add distribution management to your pom.xml:

<distributionManagement>
  <repository>
    <id>github</id>
    <name>GitHub Packages</name>
    <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url>
  </repository>
</distributionManagement>

Deploy the package:

mvn deploy

Automating with GitHub Actions

1. Create Workflow File

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Packages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 8
        uses: actions/setup-java@v4
        with:
          distribution: "temurin"
          java-version: 8
          cache: maven
          server-id: github
          server-username: module-bot
          server-password: MAVEN_TOKEN

      - name: Deploy to GitHub Packages
        run: mvn clean deploy -B -DskipTests
        env:
          MAVEN_TOKEN: ${{ secrets.MODULE_TOKEN }}

2. Configure Secrets

Go to repository Settings → Secrets
1. Add new repository secret:
  1. Name: MODULE_TOKEN
  2. Value: Your GitHub token