Checkpoint Lab — Freestyle Projects, Build Steps, Post-Build Actions, Parameters, Triggers, and Legacy Job Maintenance

1. Checkpoint mission

Create a disposable Freestyle project named legacy-release-demo that accepts bounded parameters, runs on the linux agent pool, produces one evidence artifact, archives and fingerprints it, runs once manually and once from a temporary timer, and leaves enough evidence to design a controlled migration.

2. Baseline and preflight

Jenkins 2.568.3 LTS; Java 21/25 supported; lab examples assume Java 21 on the controller and a disposable agent labeled linux.

• Disposable/local controller only.
• Built-in node executor count is 0.
• An online agent carries label linux.
• No production SCM, registry, cloud, or deployment target is used.
• No real credentials are embedded in parameters, scripts, logs, or artifacts.

Capture the controller version header, agent identity, and plugin inventory before beginning. If your controller differs from the chapter baseline, record the difference explicitly.

3. Predict state changes before touching Jenkins

Write down at least these predictions:

1. Saving the job will create durable controller-side item configuration but no build record yet.
2. Triggering the job will create a queue item and then a numbered build assigned to an eligible linux agent.
3. The shell step will create files only in that build workspace; the archive action will copy selected bytes into the Jenkins build record.
4. Enabling the timer changes job configuration; disabling it later should stop future periodic causes without deleting existing build history.

You will verify each prediction independently.

4. Configure the job

Create legacy-release-demo as a Freestyle project with:

• string parameter RELEASE_LABEL, default demo-001;
• choice parameter CHANNEL with dev and test only;
• string parameter SOURCE_SHA, default 2222222222222222222222222222222222222222;
• agent label restriction linux;
• one shell build step;
• one post-build action: Archive the artifacts for out/*, with fingerprinting enabled where available.

set -eu
case "$CHANNEL" in
  dev|test) ;;
  *) echo "Unsupported CHANNEL" >&2; exit 2 ;;
esac
case "$RELEASE_LABEL" in
  *[!A-Za-z0-9._-]*|'') echo "Invalid RELEASE_LABEL" >&2; exit 2 ;;
esac

rm -rf out
mkdir -p out
printf 'job=%s\nbuild=%s\nchannel=%s\nsource_sha=%s\nrelease_label=%s\nnode=%s\n'   "$JOB_NAME" "$BUILD_NUMBER" "$CHANNEL" "$SOURCE_SHA" "$RELEASE_LABEL" "$NODE_NAME"   > out/release-evidence.txt
sha256sum out/release-evidence.txt > out/release-evidence.sha256

The label validation is intentionally conservative. The lab does not use RELEASE_LABEL as a path, shell fragment, package version, or external deployment selector.

5. Run and verify the manual build

Start a parameterized build with RELEASE_LABEL=demo-manual, CHANNEL=dev, and the synthetic SHA. Preserve:

• job full name;
• build number, URL, result and manual cause;
• parameter values;
• queue/build timing;
• agent/node name and workspace;
• console output;
• artifact names and SHA-256 digest;
• controller and plugin baseline.

Then remove the local workspace out/ directory only after the build has completed, and verify the archived artifact remains downloadable from the build record. This proves the archive is retained evidence separate from the workspace copy.

6. Produce one timer-caused build

Temporarily enable Build periodically with H/5 * * * *. Wait for one timer run, preserve its cause and build identity, then disable the schedule immediately. The goal is a second cause, not a permanently recurring task.

If your lab constraints do not allow waiting for the timer, document that limitation and use a second manually triggered build only as a simulation; do not falsely label it as timer evidence.

7. Capture a sanitized configuration packet

Fetch the job configuration read-only with a synthetic API-token account and save it only inside the lab evidence directory:

mkdir -p evidence
curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN"   "$JENKINS_URL/job/legacy-release-demo/config.xml"   > evidence/legacy-release-demo.config.xml

curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN"   "$JENKINS_URL/job/legacy-release-demo/api/json?tree=name,url,builds[number,result,url,actions[causes[*]],actions[parameters[name,value]]]&depth=1"   > evidence/legacy-release-demo.builds.json

Review the files before sharing them. Remove tokens or sensitive provider data if any plugin unexpectedly contributes it. The token itself must never be written into the evidence files.

8. Draft the migration plan

Also identify every plugin used by the actual legacy job you are modeling. The checkpoint lab itself deliberately uses only core features so the dependency list stays small.

9. Migration acceptance criteria

• Same supported parameter domain and rejection behavior.
• Same or intentionally changed trigger behavior.
• Runs on the intended non-controller agent pool.
• Produces semantically equivalent evidence bytes from the same synthetic source identity.
• Archives the intended artifact and preserves an auditable digest.
• No real credentials are introduced into repository code, parameters, or logs.
• Rollback is defined before cutover.

10. Required evidence packet

11. Cleanup and rollback

1. Verify the timer is disabled.
2. Preserve the reviewed evidence packet outside the ephemeral workspace.
3. Delete the lab job only if you have confirmed its exact full name is legacy-release-demo and it was created for this checkpoint.
4. Remove disposable lab workspaces/agent resources created solely for the exercise.
5. Do not remove plugins as cleanup; plugin governance requires separate dependency analysis.

12. What this chapter adds to the Jenkins operating model

You can now read a Freestyle job as an operational system: controller-stored configuration creates a queueable item; causes and parameters define run context; an agent/workspace executes steps; publishers retain or forward evidence; plugins extend behavior; and build history must be correlated with configuration and external state. That skill is essential before the next chapter adds real SCM checkout, Git credentials, polling, webhooks, and multi-repository source identity.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS release and tested Java configurations.
• Working with projects — current project/job types, including Freestyle.
• Controller Isolation — why routine builds should execute on agents instead of the built-in node.
• Handling Environment Variables — security implications of build parameters and environment values.
• Remote Access API — build triggering and read-only evidence retrieval.
• Pipeline — first-class Jenkins model for versioned delivery workflows and the migration target used in this chapter.