Introduce Container‑based GitHub Action

[ascheman]

Summary

This PR adds a first‑class, Docker‑based GitHub Action for HTML Sanity Check (HSC) and a reusable container image published to GHCR. It also introduces CI jobs to build, test, and publish multi‑arch Docker images and a scheduled workflow that cleans up old, timestamped image versions from GHCR.

What’s included

• New GitHub Action backed by Docker image
  • action.yml runs using docker://ghcr.io/aim42/hsc:v2 with entrypoint '/hsc.sh'.
  • Single input args to pass through to the CLI (HscCommand).
• Reusable Docker image for independent, container‑based execution of HSC
  • Dockerfile based on eclipse-temurin:21-jre-alpine.
  • Copies shaded CLI JAR and lightweight hsc.sh entrypoint.
  • Multi‑arch builds (linux/amd64, linux/arm64).
• CI workflow for build, test, and publish
  • .github/workflows/gradle-build.yml now:
    • Builds artifacts and runs existing tests.
    • Pulls the branch‑tagged image, re‑tags as v2, and executes the new Action end‑to‑end as part of CI.
    • Publishes Docker images to GHCR via Gradle’s Docker plugin, with optional extra tags via workflow_dispatch input additional_tags.
• GHCR cleanup workflow
  • .github/workflows/cleanup-ghcr.yml removes old timestamped or stale SHA‑only image versions (default retention 14 days), while protecting latest and v* tags.

Implementation Details

• action.yml
  • runs.using: 'docker' with fixed image ghcr.io/aim42/hsc:v2 and entrypoint: '/hsc.sh'.
  • Note: If the action’s image tag changes (e.g., to v3), the test in gradle-build.yml must be updated accordingly (inline comment present).
• htmlSanityCheck-cli/Dockerfile
  • Labels include org.opencontainers.image.description and version (ARG‑driven) for provenance.
  • Uses hsc.sh to exec java -jar /hsc.jar with passed arguments.
• htmlSanityCheck-cli/build.gradle
  • Uses com.fussionlabs.gradle.docker-plugin for Buildx.
  • Tagging strategy (dockerTags):
    • Always: timestamp yyyyMMddHHmmss and sanitized branch name.
    • On main: also push v<major> (for the Action) and latest.
    • Supports additional tags via -Ddocker.image.additional.tags.
  • Multi‑arch push wired via dockerBuildMulti; dockerPush depends on it.
• .github/workflows/gradle-build.yml
  • test-gh-action pulls the branch image, tags it locally as ghcr.io/aim42/hsc:v2, and runs the Action from this repo with sample args to validate end‑to‑end behavior.
  • publish-docker-images uses the Gradle task dockerPush with Buildx multi‑arch and GitHub Packages auth via GITHUB_TOKEN.
• .github/workflows/cleanup-ghcr.yml
  • Nightly (02:00 UTC) or manual.
  • Deletes versions older than retention days when:
    • Any timestamp tag (yyyyMMddHHmmss) is older than cutoff, or
    • Only SHA‑like tags exist and version created_at/updated_at is older than cutoff, or
    • No tags at all and older than cutoff.
  • Skips versions that contain latest or v\d+ tags.
  • Defaults to dry‑run on manual dispatch; can be overridden.

Usage

• In GitHub Actions (recommended)

  - name: HTML Sanity Check
    uses: aim42/htmlSanityCheck@<ref>
    with:
      args: >-
        -r build/gh-action-test-report integration-test/common/build/docs \
        --exclude 'https://www\.baeldung\.com/.*' \
        --fail-on-errors
  

  • Replace <ref> with a tag, branch, or commit SHA of this repository.
  • The Action will run the Docker image ghcr.io/aim42/hsc:v2 under the hood.

• As a standalone Docker image

  docker run --rm \
    -v "$PWD:/work" \
    -w /work \
    ghcr.io/aim42/hsc:v2 \
    -r build/hsc-report path/to/site \
    --fail-on-errors
  

Why this change

• Provides a simple, consistent way to run HSC in CI without managing JDKs or local installs.
• Enables reproducible, containerized execution for local use and other CI systems.
• Keeps GHCR tidy by removing ephemeral, timestamped images after a retention period, saving storage and reducing clutter.

Backward compatibility

• No breaking changes to the core CLI.
• GitHub Action is new; consumers can adopt it incrementally.

Security and Permissions

• Docker images are published to GHCR using GITHUB_TOKEN with packages: write.
• Cleanup workflow only runs on schedule for main (or via manual dispatch) and skips protected tags (latest, v*).

Testing

• CI job test-gh-action validates the Action end‑to‑end using a locally retagged image matching v2.
• Artifacts and a simple report are uploaded for inspection.

Follow‑ups

• When releasing a new major, bump the Action image tag (e.g., v3) in action.yml and the test workflow.
• Optionally document the full CLI options in the project docs and link them from action.yml.

Issues

• Contributes to #343
• Closes #369