diff --git a/tasks/add-jenkins.task.md b/tasks/add-jenkins.task.md new file mode 100644 index 0000000..35b745b --- /dev/null +++ b/tasks/add-jenkins.task.md @@ -0,0 +1,165 @@ + + + +# Add a Jenkins pipeline + +Apply this task to one repository at a time. Read its local agent instructions, +README, build configuration, and existing scripts before designing the +pipeline. Preserve unrelated work, follow the repository's commit policy, and +do not push or trigger external publication unless explicitly requested. + +## Discover the CI contract + +Before writing `Jenkinsfile`, determine: + +1. the Jenkins worker label and the tools already provided by that worker; +2. the canonical repository, default branch, and any intentional publication + branches; +3. whether the checkout needs submodules, Git LFS, tags, or parent credentials; +4. the project's authoritative format, lint, test, build, package, and security + commands; +5. the exact files Jenkins should archive and whether any successful branch is + allowed to publish stable copies; +6. the destination mount, directory ownership, permissions, credential IDs, + and naming contract for publication; +7. the Gitea webhook and checks integration expected by the Jenkins + installation. + +Do not guess infrastructure values from another project. Reuse project scripts +instead of duplicating substantial build logic in Groovy or shell. Keep +language-specific setup and gates only when the target project needs them. + +## Pipeline structure + +Use a declarative `pipeline {}` with clearly named stages. A typical order is: + +1. **Checkout** — use `checkout scm`, or an explicit `GitSCM` checkout when + recursive submodules or parent credentials require it. Set + `skipDefaultCheckout(true)` when checkout is explicit. +2. **Tool setup** — verify required worker tools and report their versions. + Install missing CI tools only when that is established project policy; pin + installed versions and use the ecosystem lock mechanism where available. +3. **Quality gates** — run formatting, static analysis, dependency policy, or + other fast checks as separate stages when their failures need to be obvious. +4. **Tests** — run the repository's real unit, component, and integration test + commands before producing publishable artifacts. +5. **Build** — create outputs through the project's normal build entry point. + Verify every expected output is a regular, nonempty file before continuing. +6. **Package and archive** — create distributable names or bundles, then use + `archiveArtifacts` with fingerprinting. Never archive plaintext temporary + files, credentials, private intermediates, or other sensitive material. +7. **Publish** — when required, publish only from an explicit branch allow-list + and only after all preceding stages succeed. Non-publication branches should + finish successfully with a clear skip message. + +Add `disableConcurrentBuilds()` whenever builds write mutable shared paths or +otherwise cannot safely overlap. Put stable, non-secret configuration in the +pipeline `environment` block. Add build parameters only for real supported +inputs, with safe defaults and descriptions; validate them before passing them +to tools. + +## Shell and Groovy boundaries + +- Start nontrivial shell blocks with `set -eu`; add `set +x` before handling a + secret. Quote every path and variable expansion. +- Prefer triple-single-quoted `sh` blocks when Groovy interpolation is not + needed. Remember that Jenkins parses the Groovy before any shell runs: avoid + backslash escapes that are invalid in Groovy strings, and validate both + layers independently. +- Use Groovy interpolation only deliberately. Do not interpolate credentials or + untrusted parameters into a shell command; pass them through the environment + and quote them in the shell. +- Keep complex reusable build and deployment behavior in tracked project + scripts. A small Jenkins helper function is acceptable when it only selects + validated destinations and invokes simple publication operations. +- Fail with a useful error when a required tool, input, output, credential, or + mount is absent. Do not turn failures into success with broad `|| true` or + stale artifacts from a previous workspace. +- Clean or uniquely name transient state so an earlier build cannot make a + skipped or failed stage appear successful. + +## Credentials and sensitive outputs + +Use Jenkins credential bindings, scoped to the stage that needs them. Refer to +credentials only by their configured Jenkins ID; never commit secret values. +Disable command tracing before the value enters the environment or command +line. Ensure logs, archived artifacts, temporary files, and post-build actions +cannot expose it. + +If a build creates both protected and unprotected variants, verify the protected +output first and remove the unprotected intermediate before archiving or +publishing anything. Treat cleanup failure as a build failure. + +## Artifact and publication contract + +Keep Jenkins artifacts distinct from stable published files: + +- archive build outputs on every branch when they are useful for review; +- fingerprint archived artifacts; +- give published files stable consumer-facing names only at the destination; +- create only the required destination directories; +- validate every source before changing published state; +- copy each file to a temporary file in its destination directory and rename it + atomically over the stable name; +- set deliberate directory and file permissions when another service must read + the output; +- never recursively delete or synchronize a shared mount, and never use an + unvalidated branch name or parameter as a destination path. + +Publication policy must be visible in the Jenkinsfile. Prefer declarative +`when { branch '' }` for one branch. For multiple publication +channels, use an explicit allow-list that maps known branch names to fixed +destinations and prints a skip message for every other branch. + +## Build status reporting + +Add `post` handlers for `success`, `failure`, and `unstable`. Use +`publishChecks` when the Jenkins/Gitea installation provides it, with a stable +check name and accurate title, summary, and details. + +Messages must describe what the pipeline actually guarantees. Do not claim an +artifact was published on a branch where publication was skipped. Do not let a +notification failure conceal the original build failure. Use an always-run +cleanup action only for state that genuinely must be reconciled after both +success and failure. + +## Documentation + +Update the README or development documentation with: + +- what Jenkins checks and builds; +- required worker tools and the selected agent label; +- local equivalents of the important CI commands; +- archived artifact names; +- publication branches, destinations, and public URLs, when applicable; +- required Jenkins credential IDs without secret values; +- webhook setup at the level appropriate for the installation. + +Do not copy internal IP addresses, credentials, mount paths, branch names, or +project names from example pipelines unless they are confirmed for the target +repository. + +## Verification + +Before committing: + +1. Run the exact project commands used by every locally reproducible stage. +2. Check shell syntax for embedded or referenced scripts and exercise expected + failure cases such as missing tools or outputs. +3. Compile or lint the complete Jenkinsfile with the Jenkins installation, + Jenkins Pipeline Linter, or another compatible Groovy/Jenkins parser. Shell + syntax checking alone cannot detect Jenkinsfile parsing errors. +4. If publication exists, simulate it against a temporary absolute directory. + Verify branch selection, source validation, permissions, atomic replacement, + idempotence, and rejection of unsafe destinations without touching the real + mount. +5. Confirm archived patterns select all intended files and no secret or + plaintext intermediates. +6. Inspect the final diff for copied project identifiers, stale example values, + accidental secret exposure, and unrelated changes. +7. Commit the completed pipeline, scripts, tests, and documentation in focused, + reviewable commits. Report the commit IDs and any Jenkins-only validation + that could not be performed locally. + +Do not claim the pipeline is live or that publication succeeded until Jenkins +has parsed the committed file and completed the relevant branch build.