12 KiB
Generate and publish current CI badges
Apply this task to one repository at a time. Read its local agent instructions, inspect its existing CI, package metadata, tests, coverage setup, README, Git remote, and default branch, and preserve unrelated work. Do not commit, push, start a Jenkins build, or publish outside CI unless the user explicitly requests it.
Use the generic renderer linked under Renderer source below. If the repository already has render-version-badge.sh, render-test-badge.sh, or render-coverage-badge.sh, retain them as small compatibility wrappers when callers or tests use those interfaces; do not keep three duplicated SVG templates.
Required result
Generate exactly these mutable default-branch badges:
coverage/version.svg
coverage/test.svg
coverage/coverage.svg
Set the Jenkins publication root to /mnt/assets/coverage. Publish to:
/mnt/assets/coverage/<owner>/<project>/<default-branch>/version.svg
/mnt/assets/coverage/<owner>/<project>/<default-branch>/test.svg
/mnt/assets/coverage/<owner>/<project>/<default-branch>/coverage.svg
Serve them from:
https://assets.dandaedre.com/coverage/<owner>/<project>/<default-branch>/version.svg
https://assets.dandaedre.com/coverage/<owner>/<project>/<default-branch>/test.svg
https://assets.dandaedre.com/coverage/<owner>/<project>/<default-branch>/coverage.svg
Resolve the owner, canonical project name, and default branch from repository and CI configuration. Do not infer them only from the checkout directory, and preserve deliberate spellings.
Add all three public image references immediately below the README title. Generated SVG files and temporary coverage reports must remain ignored and untracked.
Generic renderer contract
Install the linked script as executable scripts/ci-coverage-badges.sh. It renders one badge per invocation and supplies useful defaults:
scripts/ci-coverage-badges.sh version --value 1.2.3
scripts/ci-coverage-badges.sh test --value passing
scripts/ci-coverage-badges.sh coverage --value 87.4
Without --output, those commands write the appropriate file below coverage/. Supported customizations include --text, --value, --color, --size, --height, --label-width, --value-width, --suffix, and --output.
The renderer must:
- validate its kind, options, printable text, numeric bounds, dimensions, and colors before replacing output;
- escape XML-sensitive text;
- calculate neat automatic widths with POSIX
awk, using a minimum width; - parenthesize conditional
awkexpressions for FreeBSD awk compatibility; - center text with
text-anchor="middle",dominant-baseline="middle", and half the badge height; - round numeric coverage values and select red, yellow, green, or neutral colors;
- render test values as green for
passing, red forfailing, and neutral for custom values unless a color is explicit; - create parent directories when needed;
- write a temporary file and atomically rename it over the output; and
- remove temporary files on ordinary failures and signals.
Semantic compatibility wrappers must continue to reject invalid legacy input. A version wrapper accepts the project version format, a test wrapper accepts only passing or failing, and a coverage wrapper accepts only - or a number from 0 through 100 through the generic renderer.
Coverage and test lifecycle
Use the project’s established coverage tool. For Rust, keep its conventional tracked configuration, use locked dependency resolution, pin any CI-installed coverage tool, and enforce an honest documented line-coverage floor without excluding ordinary production code.
At the beginning of the build, remove and recreate the ignored coverage/ output directory so a reused Jenkins workspace cannot provide stale markers or SVGs.
After every required test stage succeeds, create:
coverage/.tests-passed-${BUILD_NUMBER}
Separate coverage measurement from the pass/fail decision. Always display the actual measured line coverage and required floor in the CI console before reporting success or failing the coverage stage, for example:
Line coverage: 76.42%; required minimum: 80.00%
Coverage gate: FAIL (below required minimum)
Run coverage once and retain its exit status while processing its temporary
machine-readable summary. Ensure a below-threshold run still produces that
summary: if the tool cannot do so with its built-in threshold enabled, generate
the report first and enforce the same floor explicitly afterward. Do not let
shell fail-fast behavior or Jenkins' default sh failure handling abort before
printing diagnostics; capture the status explicitly and propagate failure after
reporting. Do not swallow errors with || true or lose them through a logging
pipeline.
For a complete, valid report from the current build, extract and validate the
overall percentage, print it alongside the floor, render coverage/coverage.svg,
and create the following marker even if the measured coverage is below the floor:
coverage/.coverage-ready-${BUILD_NUMBER}
The coverage-ready marker means a fresh, valid measurement and badge are ready; it does not mean the coverage gate passed. Compare the unrounded measurement against the floor, then print an explicit PASS or FAIL and fail the stage on a threshold violation or any test, tool, parsing, or rendering error. Badge rounding must not affect the gate. Retain the original tool failure diagnostics and exit status in the console even if a report is available.
If coverage cannot be measured, print Line coverage: unavailable, the required
floor, and the concrete reason before failing. Never fabricate a percentage or
use a stale or partial report. Delete temporary summaries only after diagnostics
and badge processing; cleanup must also remove them on failure. Do not create
either marker before its own prerequisites are satisfied.
Jenkins cleanup, archival, and publication
Finalize badges in post { cleanup { ... } }, which runs on both successful and failed builds:
- Render
test.svgaspassingonly if the current build’s test marker exists; otherwise renderfailing. - Preserve the measured coverage badge only if the current build’s coverage-ready marker exists; otherwise render neutral
-%. - Read the version from authoritative package or workspace metadata and render
version.svg; never duplicate the version in Jenkins configuration. - Remove temporary reports and both build-specific markers.
- Require exactly the three expected SVGs to be regular, nonempty, non-symlink files.
- Archive exactly those three SVGs with fingerprinting and
allowEmptyArchive: false. - On the resolved default branch only, publish all three badges.
Publication must run from cleanup rather than only from the success handler.
On a failed default-branch build, publish the current test status according to
the test marker and preserve fresh measured coverage, including a value below
the floor. Publish neutral -% only when no valid current-build coverage badge
is ready. Never replace a valid measurement with neutral coverage merely
because the coverage gate or a later stage failed.
Branches other than the default branch generate and archive their badges but do not modify the public default-branch files. Confirm that the Jenkins job type actually supplies the branch variable used by the predicate.
Publication script
Keep publication in a small tracked POSIX sh script. Its first argument is the already-complete root /mnt/assets/coverage; do not append another coverage component before the owner.
The script must:
- require an absolute, existing, writable publication root;
- accept only the allow-listed names
coverage,test, andversion, without duplicates; - validate every
coverage/<name>.svgsource as a regular, nonempty, non-symlink file; - resolve the destination as
<root>/<owner>/<project>/<default-branch>/; - reject symlink or non-directory owner and project components;
- migrate an old default-branch symlink by unlinking the symlink itself without deleting its target;
- create directories with mode
0755; - copy each source to a temporary file in the destination directory, set mode
0644, and atomically rename it; - clean unfinished temporary files on failure or signal;
- exit nonzero on validation, copying, permissions, or rename errors; and
- never recursively synchronize, prune, or delete the shared asset mount.
README and documentation
Place the three live public badge references directly below the README title and require each resolved URL exactly once. Remove tracked generated badges and obsolete status snapshots.
Document the exact local coverage command, enforced floor, authoritative version source, temporary summary, three archived files, publication directory, and public URLs. Update Jenkins success and failure summaries to mention tests, coverage, and badge generation accurately. Both summaries must include the measured coverage and floor, or explicitly state why coverage is unavailable.
If server configuration is outside the repository, only record that public assets should be mounted read-only, directory listing disabled, SVG served with a restrictive content security policy, and mutable URLs revalidated or given a short cache lifetime.
Verification
Before reporting repository implementation complete:
- Run the repository’s formatting, check/build, test, lint, and documentation gates.
- Run the exact coverage command and confirm the enforced floor. Exercise above-floor, exactly-at-floor, below-floor, tool/test failure, and missing/invalid report cases using fixtures or stubs where practical. Verify that the measurement and floor (or an explicit unavailable reason) appear before the stage's PASS/FAIL decision, errors still fail the job, and a valid below-floor badge survives cleanup and is selected for archival/publication. Confirm an unavailable measurement produces neutral coverage and never reuses a previous build's value.
- Exercise default and customized badge rendering, normal and long versions, passing and failing tests, all coverage color bands, neutral coverage, custom sizing, and XML-sensitive text.
- Confirm invalid kinds, options, values, dimensions, and colors fail without replacing a valid output.
- Parse every generated SVG as XML.
- Test publication against a temporary absolute root under
umask 077; verify modes, atomic replacement, idempotence, rejection cases, and safe old-symlink migration. - Confirm only the three SVG files are selected for archival.
- Confirm each public README URL appears exactly once.
- Inspect the final diff and report every unavailable check honestly.
Implementation is complete when the repository changes and local checks above pass. Real Jenkins publication and public URL retrieval are separate deployment checkpoints. If Jenkins, /mnt/assets, or the public server is unavailable, report that checkpoint as not verified; do not treat it as passed, invent results, or call the repository implementation a failure merely because production access is unavailable.
The final report must separately state README references, CI generation, Jenkins archival configuration, real default-branch publication, public URL retrieval, measured coverage, enforced floor, and checks actually run. Do not claim badges are live solely because repository files were changed.
Renderer source
Use the maintained scripts/ci-coverage-badges.sh file. Copy the script into the target repository instead of copying a stale embedded snapshot from this task, retain its executable mode, and record the source revision used when reproducibility matters.