9.3 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}
After coverage succeeds, extract and validate the overall percentage from a temporary machine-readable summary, render coverage/coverage.svg, delete the summary, and create:
coverage/.coverage-ready-${BUILD_NUMBER}
Do not create either marker early.
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: a failed default-branch build must replace stale green status with failing and stale measured coverage with neutral -%.
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.
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 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.