Introduce Container‑based GitHub Action #423

ascheman · 2025-10-10T20:53:52Z

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 Scout Rule #343
Closes make htmlSC available as GitHub Action #369

to prepare Docker build and GH action as it contains HSC and all dependencies.

The primary goal is to provide a GitHub action. Additionally, we create and publish a multi-platform Docker image for usage in other scenarios (Standalone, GitLab CI, ...).

Execute the Docker integration test only if Docker is available.

Will only be pushed on successful build and test by GitHub workflow.

Switching off Docker push leads to ERROR: failed to build: docker exporter does not currently support exporting manifest lists

The integration test must run with a local image first

Locally we build for the respective platform and test with it. Then we build a multi-platform image and push that to the Registry.

Allow a push of the Docker image with additional tags to override or extend given images.

We only need the timestamped Docker images for some time to enable testing of certain builds.

and enable optional dry-run (default true)

Copilot

Pull Request Overview

This PR introduces a container-based GitHub Action for HTML Sanity Check, enabling users to run HSC in CI/CD workflows through a published Docker image on GHCR. The implementation includes Docker multi-architecture builds, automated publishing, and GHCR cleanup workflows.

Adds a new GitHub Action (action.yml) that uses a Docker image ghcr.io/aim42/hsc:v2
Implements Docker build infrastructure with multi-arch support (amd64/arm64) and automated publishing to GHCR
Introduces automated cleanup workflow to manage old timestamped Docker images in GHCR

Reviewed Changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`action.yml`	New GitHub Action definition using Docker image with HSC entrypoint
`htmlSanityCheck-cli/Dockerfile`	Multi-stage Docker image based on Eclipse Temurin JRE Alpine
`htmlSanityCheck-cli/build.gradle`	Docker plugin configuration with multi-arch builds and tagging strategy
`htmlSanityCheck-cli/hsc.sh`	Shell entrypoint script for Docker container
`htmlSanityCheck-cli/src/main/groovy/org/aim42/htmlsanitycheck/cli/HscCommand.groovy`	Added `--fail-on-errors` CLI option
`.github/workflows/gradle-build.yml`	Added Docker image publishing and GitHub Action testing jobs
`.github/workflows/cleanup-ghcr.yml`	New workflow for cleaning up old GHCR image versions
Multiple files	Updated regex patterns to properly escape dots in URL exclusions

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

settings.gradle

htmlSanityCheck-cli/build.gradle

.github/workflows/gradle-build.yml

.github/workflows/cleanup-ghcr.yml

github-actions · 2025-10-10T21:15:13Z

Test Results

123 files ±0 123 suites ±0 10m 4s ⏱️ - 2m 32s
487 tests ±0 485 ✅ ±0 0 💤 ±0 2 ❌ ±0
627 runs ±0 562 ✅ ±0 0 💤 ±0 65 ❌ ±0

For more details on these failures, see this check.

Results for commit 689d304. ± Comparison against base commit 9efca5e.

This pull request removes 60 and adds 23 tests. Note that renamed tests count towards both.

                                <a href="http://aim.org">improve</a>' 
                                <a href="http://arc42.de">arc42.de</a> and some more text
                                <a href="https://arc42.org">arc42 over https</a> even more
                                <a href="local-file.jpg">local file</a> again, text
                                <img src="" alt="2">
                                <img src="t.doc" alt="r"> '
    <area shape="circle" coords="0,1,1" href="#test2">
    <area shape="rect" coords="0,0,1,1" href="#id1" >
    <area shape="rect" coords="0,0,1,1" href="#test1" >
    <area shape="rect" coords="0,0,1,1" href="#test1">
…

org.aim42.htmlsanitycheck.check.ImageMapsCheckerSpec ‑ find image map issues [nrOfFindings: 1, imageMapStr: <img src="image1.jpg" usemap="#map1"><map name="map1">
    <area shape="rect" coords="0,0,1,1" href="#id1" >
</map>
<h2 id="foo" >bad header</h2>, msg: ImageMap "map1" refers to missing link "id1"., #4]
org.aim42.htmlsanitycheck.check.ImageMapsCheckerSpec ‑ find image map issues [nrOfFindings: 1, imageMapStr: <img src="image1.jpg" usemap="#map1"><map name="map1">
    <area shape="rect" coords="0,0,1,1" href="#id1" >
</map>
<map name="map1">
    <area shape="rect" coords="0,0,1,1" href="#id1" >
</map>
<h2 id="id1">aim42 header</h2>, msg: 2 imagemaps with identical name "map1" exist., #1]
org.aim42.htmlsanitycheck.check.ImageMapsCheckerSpec ‑ find image map issues [nrOfFindings: 1, imageMapStr: <img src="image1.jpg" usemap="#map1"><map name="map1">
</map>
, msg: ImageMap "map1" has no area tags., #3]
org.aim42.htmlsanitycheck.check.ImageMapsCheckerSpec ‑ find image map issues [nrOfFindings: 1, imageMapStr: <map name="map1">
    <area shape="rect" coords="0,0,1,1" href="#id1" >
</map>
<h2 id="id1">aim42 header</h2>, msg: ImageMap "map1" not referenced by any image., #2]
org.aim42.htmlsanitycheck.html.HtmlPageSpec ‑ can extract alt attributes from imageTag ' <img alt="1" >
                                <img src="" alt="2">
                                <img src="t.doc" alt="r"> '
org.aim42.htmlsanitycheck.html.HtmlPageSpec ‑ detect correct number of external http links in anchors '<a href="http://arc42.org">arc42</a> and some text
                                <a href="http://arc42.de">arc42.de</a> and some more text
                                <a href="https://arc42.org">arc42 over https</a> even more
                                <a href="local-file.jpg">local file</a> again, text
                                <a href="http://aim.org">improve</a>' 
org.aim42.htmlsanitycheck.html.HtmlPageSpec ‑ detect missing alt attributes in imageTag ' <img alt="1" >
                                <img src="" alt="2">
                                <img src="t.doc" alt="r"> '
org.aim42.htmlsanitycheck.html.ImageMapParserSpec ‑ find all areas within map [nrOfAreas: 1, mapName: mymap, htmlBody: <img src="image.gif" usemap="#mymap">
<map name="mymap">
    <area shape="rect" coords="0,0,1,1" href="#test1" >
</map> , #1]
org.aim42.htmlsanitycheck.html.ImageMapParserSpec ‑ find all areas within map [nrOfAreas: 2, mapName: mymap, htmlBody: <img src="image.gif" usemap="#mymap">
<map name="mymap">
    <area shape="rect" coords="0,0,1,1" href="#test1" >
    <area shape="circle" coords="0,1,1" href="#test2">
</map> , #0]
org.aim42.htmlsanitycheck.html.ImageMapParserSpec ‑ find all hrefs within map [nrOfHrefs: 1, mapName: mymap, htmlBody: <img src="image.gif" usemap="#mymap">
<map name="mymap">
    <area shape="rect" coords="0,0,1,1" href="#test1" >
</map> , hrefs: [#test1], #1]
…

♻️ This comment has been updated with latest results.

Co-authored-by: Copilot <[email protected]>

Building a multi-platform Docker image only works in cooperation with a remote registry, which implies a push. The image is not directly available in the local image store. A pull is necessary to make it locally available. For the GitHub Action test it was necessary to use the Git SHA as unique identifier for the system to be tested (its testing the Docker image which is used as GitHub action). Other identifiers provided no clear distinction as there could be other/older images with the same tag in the remote registry.

On GH pull requests the `git branch --show-current` does not return the branch name. In this case we use the SHA tag (only) for Docker tagging.

sonarqubecloud · 2025-10-12T13:52:32Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

ascheman added 17 commits October 2, 2025 11:09

#343 Make Baeldung exclusion a real regex

a24ee72

#369 Add shadow Jar for CLI (aka. Fat Jar)

c4a25d2

to prepare Docker build and GH action as it contains HSC and all dependencies.

#369 Add Docker build and GitHub action

c58fd0b

The primary goal is to provide a GitHub action. Additionally, we create and publish a multi-platform Docker image for usage in other scenarios (Standalone, GitLab CI, ...).

#369 Add integration test for Docker

de5d1b5

#369 Restrict Integration test for Docker

a7d11b0

Execute the Docker integration test only if Docker is available.

#369 Use Docker "latest" only on "main" branch

4103350

#369 Run Docker integration test on local image

690cef7

Will only be pushed on successful build and test by GitHub workflow.

#369 Skip Docker integration test on Windows

ba8fc1a

#369 Fix Docker build by pushing anyway

61d0fbd

Switching off Docker push leads to ERROR: failed to build: docker exporter does not currently support exporting manifest lists

#369 Add documentation for Docker run

f7ea603

#369 Enable fail-on-error for CLI

f658832

#369 Test GitHub action

a81384f

#369 Build Docker locally and fail on errors

1bb0eb3

The integration test must run with a local image first

#369 Separate Docker build(s)

7aacf0c

Locally we build for the respective platform and test with it. Then we build a multi-platform image and push that to the Registry.

#369 Enable additional Docker tags

ce446c3

Allow a push of the Docker image with additional tags to override or extend given images.

#369 Add housekeeping for timestamped images

19a95a3

We only need the timestamped Docker images for some time to enable testing of certain builds.

#369 Clean up untagged packages also

09784cf

and enable optional dry-run (default true)

ascheman requested review from gernotstarke and truhroth October 10, 2025 20:53

ascheman self-assigned this Oct 10, 2025

Copilot AI review requested due to automatic review settings October 10, 2025 20:53

Copilot AI reviewed Oct 10, 2025

View reviewed changes

settings.gradle Show resolved Hide resolved

htmlSanityCheck-cli/build.gradle Show resolved Hide resolved

.github/workflows/gradle-build.yml Outdated Show resolved Hide resolved

.github/workflows/cleanup-ghcr.yml Show resolved Hide resolved

ascheman and others added 2 commits October 12, 2025 08:57

Fix GH Caching key YAML

89d686c

Co-authored-by: Copilot <[email protected]>

ascheman force-pushed the feature/369-gh-action branch from a51b419 to 675d6d7 Compare October 12, 2025 07:22

#369 Use SHA for Docker tags if no branch detected

689d304

On GH pull requests the `git branch --show-current` does not return the branch name. In this case we use the SHA tag (only) for Docker tagging.

ascheman added the hacktoberfest-accepted label Oct 29, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Introduce Container‑based GitHub Action #423

Introduce Container‑based GitHub Action #423

Uh oh!

ascheman commented Oct 10, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 10, 2025 •

edited

Loading

Uh oh!

sonarqubecloud bot commented Oct 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Introduce Container‑based GitHub Action #423

Are you sure you want to change the base?

Introduce Container‑based GitHub Action #423

Uh oh!

Conversation

ascheman commented Oct 10, 2025

Summary

What’s included

Implementation Details

Usage

Why this change

Backward compatibility

Security and Permissions

Testing

Follow‑ups

Issues

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

sonarqubecloud bot commented Oct 12, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Oct 10, 2025 •

edited

Loading