Add GitHub Packages Maven repository as JitPack alternative

[ascheman]

Problem

JitPack has reliability issues that impede development workflow:

• New branches don't show up: Newly created development branches are not discoverable/accessible in JitPack
• Stale builds: Updates to existing branches don't always trigger rebuilds, especially after force pushes
• Build timeouts: First access or cache expiry can cause long delays
• Difficult to debug: Hard to understand when builds fail or don't update

This affects developers and users trying to test unreleased features or bug fixes from development branches, particularly when iterating with force pushes during development.

Existing Workaround (Incomplete)

A local script exists to set branch-based versions (similar to JitPack's versioning scheme):

jitpack.sh - Reference implementation for branch-based versioning

#!/usr/bin/env bash

set -eu -o pipefail

version="$(git branch --show-current 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || git rev-parse --verify HEAD 2>/dev/null || true)"
if test -z "${version}"; then
  echo "Current git branch name could not be determined!" >&2
  env | sort
  exit 1
else
  case "${version}" in
    */*)
      version="${version//\//\~}-SNAPSHOT"
      sed -r -i.bak -e "s/^htmlSanityCheckVersion=.+/htmlSanityCheckVersion='$version'/g" gradle.properties
      ;;
    *)
      version="${version#refs/tags/}"
      ;;
  esac
fi

./gradlew clean build publishToMavenLocal -x test

test -r gradle.properties.bak && mv gradle.properties.bak gradle.properties

Limitations: This script demonstrates the version transformation logic (branch name → branch~name-SNAPSHOT) but only publishes to local Maven repository, which doesn't make artifacts available to other developers or users.

Proposed Solution

Add GitHub Packages Maven repository as an additional publishing target alongside Maven Central and JitPack.

Benefits

1. Build control: We control when/how artifacts are published, not relying on on-demand builds
2. Predictable updates: New branches and updates are available as soon as published
3. Force push friendly: No stale cache issues after force pushes
4. Better integration: Native GitHub integration (Actions, releases, etc.)
5. Multiple options: Users can choose between JitPack and GitHub Packages

Implementation

Publishing Configuration

Add GitHub Packages as a publishing target in JReleaser configuration.

JReleaser already supports GitHub Packages publishing - we need to:

1. Configure GitHub Packages Maven deployer in jreleaser.yml
2. Set up credentials (GITHUB_TOKEN)
3. Configure which artifacts/versions to publish

Reference: JReleaser GitHub Packages Documentation

Branch-based Versioning (branch2version)

Requirement: Support publishing from both local machine AND GitHub Actions with branch-based versioning similar to JitPack.

Versioning strategy:

• Branch name with / replaced by ~ + -SNAPSHOT suffix
• Example: bugfix/429-maven-sourcedocs-optional → bugfix~429-maven-sourcedocs-optional-SNAPSHOT

Implementation options:

1. Gradle-based approach (preferred): Implement version derivation in build.gradle to automatically detect branch name and transform it:

   version = providers.exec {
       commandLine("git", "branch", "--show-current")
   }.standardOutput.asText.get().trim().replace('/', '~') + '-SNAPSHOT'
   

   This approach integrates the branch2version logic directly into the build, avoiding the need for external scripts and gradle.properties manipulation.

2. Script-based approach (alternative): Use a script similar to the reference implementation above but publishing to GitHub Packages instead of local Maven repository. The script above demonstrates the core version transformation logic that could be adapted.

Both approaches should work for:

• Local developer machine publishing
• GitHub Actions automated publishing

CI/CD Integration

• Publish to GitHub Packages on push to develop branch
• Publish to GitHub Packages on tagged releases (in addition to Maven Central)
• Use GITHUB_TOKEN provided by GitHub Actions
• Support manual publishing from developer machines with appropriate credentials

Documentation Updates

Update the following files to document GitHub Packages usage:

1. Main README.adoc: Add GitHub Packages as alternative to JitPack
2. Plugin READMEs: Add configuration examples for consuming from GitHub Packages
3. Development docs: Document publishing process (both CI and local)
4. Developer guide: Document how to publish branch-based snapshots locally

Usage Example

For Gradle users:

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/aim42/htmlSanityCheck")
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
            password = project.findProperty("gpr.token") ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation "org.aim42.htmlSanityCheck:htmlSanityCheck-core:bugfix~429-maven-sourcedocs-optional-SNAPSHOT"
}

For Maven users:

<repository>
    <id>github</id>
    <url>https://maven.pkg.github.com/aim42/htmlSanityCheck</url>
</repository>

<dependency>
    <groupId>org.aim42.htmlSanityCheck</groupId>
    <artifactId>htmlSanityCheck-core</artifactId>
    <version>bugfix~429-maven-sourcedocs-optional-SNAPSHOT</version>
</dependency>

Considerations

1. Authentication Required: GitHub Packages requires authentication even for public repositories (read access needs a token)
2. Token Management: Users need to create a Personal Access Token with read:packages scope
3. Keep JitPack: Maintain JitPack support for users who prefer unauthenticated access
4. Versioning: Use branch-based versioning strategy (branch name with / → ~ + -SNAPSHOT)
5. JReleaser Configuration: Extend existing JReleaser setup rather than adding separate publishing logic
6. Local Publishing: Support both local developer publishing and CI-based publishing

References

• JReleaser GitHub Packages Documentation
• GitHub Packages Documentation
• Gradle Dynamic Versions