Add sealed CI integration: a GitHub Action and a GitLab CI template

scripts/validate.sh is the engine behind both platforms: download the released standalone jar and the validation configuration (SHA-256-verified when pinned), validate each document, print PASS/FAIL with the failing rule ids and fail on any rejection.
The GitHub Action (action.yml) maps its inputs onto the script's environment; the GitLab template fetches the same script from this repository at KOSIT_SCRIPT_REF and drives it with the same variables, so both platforms run identical logic.
With Docker available the action executes each validation sealed (the "sealed" input, default "auto"): inside an eclipse-temurin:21-jre container without network access, a read-only root and no capabilities, with only the jar, the configuration and a scratch directory mounted; downloads always happen outside the container, so the validator itself never touches the network, and the host JVM setup is skipped entirely for "sealed: always".
The image tag pins the Java 21 JRE contract and floats the patch level: the released jars are the checksummed artifacts, the runtime is a security-patch channel; an "image" input (KOSIT_IMAGE on GitLab) accepts a digest-pinned reference for stricter policies.
The GitLab job image is the same runtime, giving both platforms an identical execution environment, and a devcontainer provides the matching Maven and Java setup for development.
The action self-test validates a conformant XRechnung reference instance and asserts a corrupted one is rejected, exercising the sealed path through the empty-input fallback and an explicit image override, plus the host path.
This commit is contained in:
Stefan Grönke 2026-07-23 10:34:59 +00:00
parent 86d9ddfa2b
commit ba93207b77
7 changed files with 445 additions and 0 deletions

6
.devcontainer/Dockerfile Normal file
View file

@ -0,0 +1,6 @@
# Development container for the validator: Maven 3 with Temurin 21, the
# same Java family the CI action and the GitLab template execute the
# released jar with (eclipse-temurin:21-jre). The tag pins that contract
# and floats the patch level, so JDK and Maven security updates arrive
# without a change to this repository.
FROM maven:3-eclipse-temurin-21

View file

@ -0,0 +1,7 @@
{
"name": "KoSIT Validator",
"build": {
"dockerfile": "Dockerfile"
},
"postCreateCommand": "mvn --version"
}

93
.github/workflows/action-test.yml vendored Normal file
View file

@ -0,0 +1,93 @@
name: Action self-test
on:
pull_request:
paths:
- action.yml
- scripts/**
- gitlab/**
- .github/workflows/action-test.yml
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
env:
CONFIGURATION_URL: https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/v2026-01-31/xrechnung-3.0.2-validator-configuration-2026-01-31.zip
CONFIGURATION_SHA256: 6a5a5911a421b25fbc423f62f93f894df7b236f5d73ca4f84bb222a945082704
VALIDATOR_SHA256: 244978514ad48f67c7573acfffc8f4fd73d81feda6f276710033f9913579857e
# A conformant XRechnung 3.0.2 reference instance from the KoSIT test suite.
SAMPLE_URL: https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/b3791d47a2e1446b1751a27cb732aac294231293/src/test/business-cases/standard/01.01a-INVOICE_uncefact.xml
jobs:
accepts-a-valid-document:
runs-on: ubuntu-latest
timeout-minutes: 10
strategy:
matrix:
# "always" proves the sealed Docker path — once through the
# empty-input fallback, once with an explicit image override —
# and "never" the host JVM path.
include:
- sealed: always
image: ""
- sealed: always
image: eclipse-temurin:21-jre
- sealed: never
image: ""
steps:
- uses: actions/checkout@v7
- name: Fetch a conformant reference instance
run: |
mkdir samples
curl -fsSL "$SAMPLE_URL" -o samples/invoice.xml
- name: Validate (must accept)
id: validate
uses: ./
with:
version: "1.6.2"
checksum: ${{ env.VALIDATOR_SHA256 }}
configuration: ${{ env.CONFIGURATION_URL }}
configuration-checksum: ${{ env.CONFIGURATION_SHA256 }}
files: samples/
sealed: ${{ matrix.sealed }}
image: ${{ matrix.image }}
- name: Outputs are reported
run: |
test "${{ steps.validate.outputs.accepted }}" = "1"
test "${{ steps.validate.outputs.rejected }}" = "0"
test -d "${{ steps.validate.outputs.report-dir }}"
rejects-a-broken-document:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v7
- name: Fetch and break a reference instance
run: |
mkdir samples
curl -fsSL "$SAMPLE_URL" -o samples/invoice.xml
# Corrupt the issue date (BT-2): schema-invalid, must be rejected.
sed -i '0,/format="102">[0-9]*</s//format="102">not-a-date</' samples/invoice.xml
- name: Validate (must reject)
id: validate
continue-on-error: true
uses: ./
with:
version: "1.6.2"
checksum: ${{ env.VALIDATOR_SHA256 }}
configuration: ${{ env.CONFIGURATION_URL }}
configuration-checksum: ${{ env.CONFIGURATION_SHA256 }}
files: samples/invoice.xml
sealed: always
- name: The action failed as required
run: |
test "${{ steps.validate.outcome }}" = "failure"

View file

@ -100,6 +100,26 @@ java -jar validator-<version>-standalone.jar -s <scenario-config-file> -D
The [daemon documentation](./docs/daemon.md) shows more usage details and further configuration options.
### Continuous Integration
The repository ships a GitHub Action and a GitLab CI template so documents can be validated as part of a pipeline.
Validate a directory of XML documents against the current XRechnung configuration with the GitHub Action:
```yaml
- uses: itplr-kosit/validator@main
with:
version: "1.6.2"
configuration: "https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/v2026-01-31/xrechnung-3.0.2-validator-configuration-2026-01-31.zip"
files: invoices/
```
The action downloads the released standalone jar, runs every document and fails the job if any document is rejected, printing the failing rule ids. The optional `checksum` and `configuration-checksum` inputs verify the downloads against a SHA-256 pin. The reports are written to `report-dir` (default `validator-reports`), and the `accepted`/`rejected` counts are exposed as outputs.
When Docker is available on the runner the action executes the validator inside an `eclipse-temurin:21-jre` container without network access, a read-only root and no capabilities; downloads always happen outside the container, so the validator itself never touches the network. The `sealed` input controls this (`auto` default, `always`, `never`), and the `image` input replaces the default image — the floating tag receives Java security patches automatically, while a digest-pinned reference can be passed for a stricter supply-chain policy.
On GitLab, include [`gitlab/validator.gitlab-ci.yml`](./gitlab/validator.gitlab-ci.yml) and extend the `.kosit-validate` job template; its variables mirror the action inputs and its job image is the same pinned runtime the sealed action uses, so both platforms execute the validator in an identical environment.
## Packages
The Validator distribution contains the following artifacts:

101
action.yml Normal file
View file

@ -0,0 +1,101 @@
name: KoSIT Validator
description: >-
Validate XML documents against a validator configuration (e.g. XRechnung)
using the KoSIT validator. Downloads a released validator jar, optionally
verifies checksums, runs each file and fails if any document is rejected.
author: KoSIT contributors
branding:
icon: check-circle
color: green
inputs:
version:
description: >-
Validator release to use (a tag of this repository without the leading
"v", e.g. "1.6.2"). The standalone jar is downloaded from the GitHub
release of this repository.
required: false
default: "1.6.2"
checksum:
description: >-
Optional SHA-256 checksum of the validator jar. When set, the download
is verified against it and the action fails on a mismatch.
required: false
default: ""
configuration:
description: >-
The validator configuration: either a URL to a configuration zip (for
example a release asset of validator-configuration-xrechnung) or a
path to an already unpacked configuration directory containing
scenarios.xml.
required: true
configuration-checksum:
description: >-
Optional SHA-256 checksum of the configuration zip. Only used when
"configuration" is a URL.
required: false
default: ""
files:
description: >-
XML documents to validate: a file, a directory (validated recursively,
*.xml) or a shell glob.
required: true
report-dir:
description: Directory the validation reports are written to.
required: false
default: validator-reports
sealed:
description: >-
Execute the validator inside a Docker container without network access,
a read-only root and no capabilities. "auto" (default) seals when
Docker is available and falls back to the host JVM otherwise; "always"
fails when Docker is unavailable; "never" always uses the host JVM.
Downloads are always performed on the host, so the validator itself
never needs the network.
required: false
default: auto
image:
description: >-
Container image for the sealed execution. The default floats on the
Java 21 JRE contract so runtime security patches arrive without a
change to this repository; pass a digest-pinned reference for a
stricter supply-chain policy.
required: false
default: eclipse-temurin:21-jre
outputs:
report-dir:
description: Directory containing the validation reports.
value: ${{ steps.validate.outputs.report-dir }}
accepted:
description: Number of accepted documents.
value: ${{ steps.validate.outputs.accepted }}
rejected:
description: Number of rejected documents.
value: ${{ steps.validate.outputs.rejected }}
runs:
using: composite
steps:
# The host JVM is only used by unsealed runs: "never", or "auto" on a
# runner without Docker. "always" executes exclusively in the container.
- name: Set up Java
if: ${{ inputs.sealed != 'always' }}
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: "21"
- name: Validate
id: validate
shell: bash
env:
KOSIT_VERSION: ${{ inputs.version }}
KOSIT_CHECKSUM: ${{ inputs.checksum }}
KOSIT_CONFIGURATION: ${{ inputs.configuration }}
KOSIT_CONFIGURATION_CHECKSUM: ${{ inputs.configuration-checksum }}
KOSIT_FILES: ${{ inputs.files }}
KOSIT_REPORT_DIR: ${{ inputs.report-dir }}
KOSIT_SEALED: ${{ inputs.sealed }}
KOSIT_IMAGE: ${{ inputs.image }}
run: bash "$GITHUB_ACTION_PATH/scripts/validate.sh"

View file

@ -0,0 +1,55 @@
# Reusable GitLab CI template for the KoSIT validator.
#
# Include it and extend the hidden job:
#
# include:
# - remote: "https://raw.githubusercontent.com/itplr-kosit/validator/<ref>/gitlab/validator.gitlab-ci.yml"
#
# validate-invoices:
# extends: .kosit-validate
# variables:
# KOSIT_SCRIPT_REF: "<ref>"
# KOSIT_CONFIGURATION: "https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/v2026-01-31/xrechnung-3.0.2-validator-configuration-2026-01-31.zip"
# KOSIT_FILES: "invoices/"
#
# The job fetches scripts/validate.sh — the same engine the GitHub Action
# runs — from this repository at KOSIT_SCRIPT_REF. Use the same ref for
# the include and the script, and pin a tag or commit for reproducible
# pipelines. The variables are the script's interface:
#
# KOSIT_VERSION validator release, default 1.6.2
# KOSIT_CHECKSUM optional SHA-256 of the validator jar
# KOSIT_CONFIGURATION configuration zip URL, or a path to an
# unpacked configuration with scenarios.xml
# KOSIT_CONFIGURATION_CHECKSUM optional SHA-256 of the configuration zip
# KOSIT_FILES file, directory or glob of XML documents
# KOSIT_REPORT_DIR report output directory, default validator-reports
#
# The job image is the same runtime the GitHub Action uses for its sealed
# execution, so both platforms run the validator in an identical
# environment. The tag pins the Java 21 JRE contract and floats the patch
# level; override KOSIT_IMAGE with a digest-pinned reference for a
# stricter policy. Docker is not available inside the job container, so
# the script runs its host path — which here already is the pinned image.
.kosit-validate:
image: $KOSIT_IMAGE
variables:
KOSIT_IMAGE: "eclipse-temurin:21-jre"
KOSIT_SCRIPT_REF: "main"
KOSIT_VERSION: "1.6.2"
KOSIT_CHECKSUM: ""
KOSIT_CONFIGURATION: ""
KOSIT_CONFIGURATION_CHECKSUM: ""
KOSIT_FILES: ""
KOSIT_REPORT_DIR: "validator-reports"
KOSIT_SEALED: "never"
KOSIT_CACHE: "$CI_PROJECT_DIR/.kosit-cache"
script:
- apt-get update -qq >/dev/null && apt-get install -qqy --no-install-recommends curl unzip >/dev/null
- curl -fsSL "https://raw.githubusercontent.com/itplr-kosit/validator/$KOSIT_SCRIPT_REF/scripts/validate.sh" -o /tmp/kosit-validate.sh
- bash /tmp/kosit-validate.sh
artifacts:
when: always
paths:
- $KOSIT_REPORT_DIR

163
scripts/validate.sh Executable file
View file

@ -0,0 +1,163 @@
#!/usr/bin/env bash
# Validate XML documents with a released validator jar. The shared engine
# behind the GitHub Action (action.yml) and the GitLab CI template
# (gitlab/validator.gitlab-ci.yml); configured through environment
# variables so both platforms drive the identical logic.
#
# KOSIT_VERSION validator release, e.g. "1.6.2"
# KOSIT_CHECKSUM optional SHA-256 of the validator jar
# KOSIT_CONFIGURATION URL of a configuration zip, or path to an
# unpacked configuration containing scenarios.xml
# KOSIT_CONFIGURATION_CHECKSUM optional SHA-256 of the configuration zip
# KOSIT_FILES file, directory (recursive *.xml) or glob
# KOSIT_REPORT_DIR report output directory (default validator-reports)
# KOSIT_SEALED auto (default) | always | never — run the
# validator in a Docker container without network,
# a read-only root and no capabilities
# KOSIT_IMAGE container image for sealed runs (default
# eclipse-temurin:21-jre; floats the Java 21 JRE
# contract — pass a digest-pinned reference for a
# stricter policy)
# KOSIT_CACHE download cache directory
#
# Exit 0 iff every document is accepted. When GITHUB_OUTPUT is set, the
# accepted/rejected counts and the report directory are written to it.
set -euo pipefail
VERSION="${KOSIT_VERSION:-1.6.2}"
CHECKSUM="${KOSIT_CHECKSUM:-}"
CONFIGURATION="${KOSIT_CONFIGURATION:-}"
CONFIGURATION_CHECKSUM="${KOSIT_CONFIGURATION_CHECKSUM:-}"
FILES="${KOSIT_FILES:-}"
REPORT_DIR="${KOSIT_REPORT_DIR:-validator-reports}"
SEALED="${KOSIT_SEALED:-auto}"
IMAGE="${KOSIT_IMAGE:-eclipse-temurin:21-jre}"
CACHE="${KOSIT_CACHE:-${RUNNER_TEMP:-/tmp}/kosit-validator}"
verify() { # <checksum> <file>
if command -v sha256sum >/dev/null 2>&1; then
echo "$1 $2" | sha256sum -c - >/dev/null
else
echo "$1 $2" | shasum -a 256 -c - >/dev/null
fi
}
mkdir -p "$CACHE"
jar="$CACHE/validator-$VERSION-standalone.jar"
if [ ! -f "$jar" ]; then
echo "Downloading validator $VERSION..."
curl -fsSL \
"https://github.com/itplr-kosit/validator/releases/download/v$VERSION/validator-$VERSION-standalone.jar" \
-o "$jar"
fi
if [ -n "$CHECKSUM" ]; then
verify "$CHECKSUM" "$jar"
fi
case "$CONFIGURATION" in
http://*|https://*)
config_dir="$CACHE/configuration"
if [ ! -f "$config_dir/scenarios.xml" ]; then
echo "Downloading configuration..."
curl -fsSL "$CONFIGURATION" -o "$CACHE/configuration.zip"
if [ -n "$CONFIGURATION_CHECKSUM" ]; then
verify "$CONFIGURATION_CHECKSUM" "$CACHE/configuration.zip"
fi
unzip -o -q "$CACHE/configuration.zip" -d "$config_dir"
fi
;;
*)
config_dir="$CONFIGURATION"
;;
esac
if [ ! -f "$config_dir/scenarios.xml" ]; then
echo "No scenarios.xml in configuration: $CONFIGURATION" >&2
exit 2
fi
shopt -s nullglob
files=()
if [ -d "$FILES" ]; then
while IFS= read -r f; do files+=("$f"); done \
< <(find "$FILES" -name '*.xml' -type f | sort)
else
for f in $FILES; do files+=("$f"); done
fi
if [ "${#files[@]}" -eq 0 ]; then
echo "No XML documents matched: $FILES" >&2
exit 2
fi
# Sealed execution: the validator runs in a JRE container with no network,
# a read-only root and no capabilities; only the jar, the configuration and
# a scratch directory are mounted. Downloads happened above, on the host.
use_docker=0
case "$SEALED" in
never) ;;
always)
if ! docker info >/dev/null 2>&1; then
echo "KOSIT_SEALED=always, but Docker is unavailable" >&2
exit 2
fi
use_docker=1
;;
auto|"")
if docker info >/dev/null 2>&1; then use_docker=1; fi
;;
*)
echo "Unknown value for KOSIT_SEALED: $SEALED" >&2
exit 2
;;
esac
run_validator() { # <document> <report-dir>
if [ "$use_docker" = "1" ]; then
workdir="$(mktemp -d "${RUNNER_TEMP:-/tmp}/kosit-run.XXXXXX")"
cp "$1" "$workdir/$(basename "$1")"
mkdir -p "$workdir/reports"
docker run --rm --network none --read-only --tmpfs /tmp \
--cap-drop ALL --security-opt no-new-privileges \
--user "$(id -u):$(id -g)" -e HOME=/tmp \
-v "$jar:/opt/validator.jar:ro" \
-v "$config_dir:/opt/configuration:ro" \
-v "$workdir:/work" -w /work \
"$IMAGE" \
java -jar /opt/validator.jar -s /opt/configuration/scenarios.xml \
-r /opt/configuration -o /work/reports "/work/$(basename "$1")"
status=$?
cp "$workdir/reports/"* "$2"/ 2>/dev/null || true
rm -rf "$workdir"
return "$status"
fi
java -jar "$jar" -s "$config_dir/scenarios.xml" \
-r "$config_dir" -o "$2" "$1"
}
mkdir -p "$REPORT_DIR"
rule_ids='\[[A-Z][A-Z0-9]*(-[A-Z0-9]+)+\]'
accepted=0
rejected=0
for f in "${files[@]}"; do
if output="$(run_validator "$f" "$REPORT_DIR" 2>&1)"; then
accepted=$((accepted + 1))
echo "PASS $f"
else
rejected=$((rejected + 1))
report="$REPORT_DIR/$(basename "${f%.xml}")-report.xml"
ids="$( { printf '%s' "$output"; [ -f "$report" ] && cat "$report"; } \
| grep -oE "$rule_ids" | sort -u | paste -sd' ' - || true)"
echo "FAIL $f ${ids:-<no rule id parsed>}"
printf '%s\n' "$output" | grep -iE 'rejected|error' || true
fi
done
if [ -n "${GITHUB_OUTPUT:-}" ]; then
{
echo "report-dir=$REPORT_DIR"
echo "accepted=$accepted"
echo "rejected=$rejected"
} >> "$GITHUB_OUTPUT"
fi
echo "Accepted: $accepted Rejected: $rejected"
[ "$rejected" -eq 0 ]