Jenkins / Persistent state and controlled delivery / Lesson 17

Candidate promotion and compatibility-aware recovery

Connect tested bytes, decision authority, configuration, and observed adoption without rebuilding in secret.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Separate artifact identity, environment configuration, and target observation.
Evaluate recovery beyond restoring an older application package.

Promote the identified tested output

Parcel should produce a candidate once and carry its immutable identity through tests and the release decision. Rebuilding inside a later approval stage can resolve changed dependencies or tools, so the approved source label alone does not prove the bytes match. Retain source, run, library identities, relevant build inputs, package identity, and required evidence. Jenkins run artifacts can participate in that record but do not automatically provide a complete authenticated release system. Consumers must know how expected identities are obtained and verified.

Adoption combines several controlled inputs

The same package can behave differently under environment settings, feature exposure, secrets, and external dependencies. Record configuration identity separately without exposing sensitive values. A stage named production is not proof of the destination actually resolved by a helper or credential. Before authority is exercised, identify candidate, configuration, target, and authorized decision. After submission, distinguish accepted request, observed convergence, and user-visible health. A successful Pipeline command may prove only one of these boundaries rather than completed service adoption.

Describe the release relationship explicitly

The JSON record below is an abbreviated synthetic review request, not a deployment payload or provenance format. It keeps candidate, configuration, and target visible without inventing hashes or credentials. A real review needs authenticated producer and decision evidence and appropriate retention. Do not let a mutable latest lookup replace the candidate while waiting. If evidence expires or relevant vulnerabilities change the decision context, apply the release policy’s re-evaluation rule rather than treating an old manual approval as permanent authority.

json A synthetic promotion request

{"candidate":"parcel-lab-r8","configuration":"staging-c4","target":"staging-lab","source":"lab-source-r8","decision":"pending"}

The labels are teaching inputs, not actual commits, digests, endpoints, or approvals. This record cannot authenticate provenance or perform a release, and no target is contacted.

Old code must still understand current state

A package rollback restores bytes, not automatically database schema, queued messages, external purchases, or configuration. During mixed-version adoption, old and new instances may share durable state. Use compatibility-preserving evolution and retain a recovery candidate appropriate to the current state. A destructive schema contraction can invalidate the previous package even when its archive still exists. Data restoration and business compensation require their own owner-led process. Do not promise that a familiar Jenkins button reverses every effect of an application release.

Require retained and compatible recovery material

The complete local model below checks whether a retained synthetic package supports the observed schema label. It rejects a newer schema outside the declared set. This is not a database inspection or proof of real migration reversibility. Actual compatibility includes application data meanings, configuration, queues, APIs, and external effects beyond one number. A tabletop model can expose a missing decision before an incident; a separately authorized disposable exercise is needed to establish real mechanics and timing. Keep recovery completion tied to restored user behavior and observed identities.

python A declared recovery-compatibility model

recovery = {"retained": True, "supported_schemas": {4, 5}}
def usable(schema):
    return recovery["retained"] and schema in recovery["supported_schemas"]
print(usable(5))
print(usable(6))

Expected output

True
False

The schema numbers are synthetic labels. No package is downloaded, database queried, or recovery operation executed.

Common errors and fixes

An approved stage rebuilds a package with different inputs.

Why it happens: Source approval was substituted for continuity of tested bytes.
How to fix it: Promote the identified tested candidate or explicitly validate the new candidate.
Prevent it next time: Retain source-to-run-to-package relationships.

A successful submission is described as healthy completed adoption.

Why it happens: Request acceptance was confused with target convergence and user outcome.
How to fix it: Collect observed candidate, configuration, and relevant health evidence.
Prevent it next time: Define release completion beyond command status.

The previous archive is restored against an incompatible schema.

Why it happens: Retention was mistaken for recovery compatibility.
How to fix it: Evaluate current state and choose a compatible owner-approved recovery path.
Prevent it next time: Maintain compatibility evidence across the recovery horizon.

Check your understanding

1. The package digest is unchanged but the environment endpoint changes. Is there a release-relevant difference?

Show worked solution

Yes. The adoption configuration changed and can alter behavior or destination. Review and validate that change, retain its identity, and verify the intended target. Package equality does not establish equal runtime conditions.

2. A tabletop recovery finishes quickly. Can the team claim that duration as production recovery time?