agent-tasks/tasks/add-jenkins.task.md

8.9 KiB

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:

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.