179 lines
8.9 KiB
Markdown
179 lines
8.9 KiB
Markdown
<!-- 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.
|
|
|
|
## Known reference pipelines
|
|
|
|
Use the closest known Jenkinsfile as a structural reference, then confirm every
|
|
project-specific value against the target repository:
|
|
|
|
- [Rust (`vsg-bridge-ls`)](https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls/raw/branch/main/Jenkinsfile)
|
|
- [Websites (`SOTV_Websites`)](https://proxy.dandaedre.com/gitea/Books/SOTV_Websites/raw/branch/main/Jenkinsfile)
|
|
- [Books/Typst (`ravenous_typst`)](https://proxy.dandaedre.com/gitea/Ravenous/ravenous_typst/raw/branch/candlelight/Jenkinsfile)
|
|
|
|
These are known-good examples, not drop-in templates. Do not copy credentials,
|
|
worker labels, paths, branches, publication rules, or project identifiers
|
|
without verifying them for the target repository.
|
|
|
|
## 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.
|