Add generic Jenkins pipeline task
Dandaedre/agent-tasks/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-10-03 00:58:28 +02:00
parent 8fdc2913d0
commit 119173c865
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
1 changed files with 165 additions and 0 deletions

165
tasks/add-jenkins.task.md Normal file
View File

@ -0,0 +1,165 @@
<!-- Purpose: Add a maintainable Jenkins declarative pipeline to a repository. -->
<!-- Scope: Build, verify, archive, and optionally publish project artifacts safely. -->
# 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 '<default-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.