Add generic Jenkins pipeline task
Dandaedre/agent-tasks/pipeline/head This commit looks good
Details
Dandaedre/agent-tasks/pipeline/head This commit looks good
Details
This commit is contained in:
parent
8fdc2913d0
commit
119173c865
|
|
@ -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.
|
||||
Loading…
Reference in New Issue