START HERE
What you will learn
- Distinguish source revisions, built artifacts and deployed releases.
- Define an approval path that checks the exact candidate reaching production.
- Plan environment configuration, concurrency and rollback deliberately.
Before you start: A repository, repeatable build commands and prepared staging/production targets. An authorised maintainer must configure deployment credentials and approval rules.
Reference edition: Fictional website walkthrough; providers are examples, not required services. Sources checked 2026-11-13.
Source control records a change; a pipeline makes it repeatable
A contributor proposes an edit on a branch or through an editor that creates one. A change request records the diff and its purpose. Automated checks install locked dependencies, build the site and run relevant quality and behaviour checks. Successful checks create a candidate, not automatic permission to publish it.
The deployment workflow records the revision, artifact identity, target environment and outcome. A release marker or equivalent public check lets an operator confirm what is actually serving. A green build badge alone cannot show that the upload, restart, DNS route or public enquiry path worked.
Separate configuration from secrets
Public configuration includes items a visitor may legitimately inspect, such as a form endpoint. Secrets include deployment credentials and email-provider keys. Keep secrets out of the repository, frontend bundle and ordinary build logs. Limit when each job receives them and which environment it may affect.
A pipeline environment named production is not an approval rule by itself. Configure the relevant branch restrictions and protection policy. In GitHub Actions, some reviewer and protection features depend on the repository visibility and plan; verify availability rather than assuming a YAML label enables review. Use a supported equivalent control if a particular feature is unavailable.
Be precise about promoting a release
The strongest simple promotion story is to build one artifact, identify it by revision and digest, review that artifact in staging and promote it unchanged when the environment model permits. Keep secrets and environment-specific server configuration outside it.
Some frontends embed public configuration at build time, so staging and production legitimately need different builds. In that case, pin both to the approved source revision, record each build’s configuration and artifact identity, and repeat the relevant checks on the production candidate. Do not describe separately rebuilt bundles as identical artifacts. A staging noindex flag or test email endpoint must not silently become public configuration.
Deploy without overwriting the only working copy
Upload the candidate into a new release location, validate the expected files, run a health check and switch the serving reference using the host’s supported deployment mechanism. Serialise changes to each environment so two releases do not race. Keep a known working reference and a rollback procedure.
For a VM using SSH, use a constrained deployment identity and verified host key. For managed hosts, apply the equivalent scoped deploy token or federated identity where supported. Hosted CI network access must fit the host’s administrative access policy. Do not turn off identity verification to make a failing connection pass.
Review behaviour before and after approval
Staging review includes real navigation, direct article URLs, small-screen behaviour, metadata, form states and test email routing. Record the exact candidate and known limitations. The approver should understand what changes and which evidence supports release.
After production deploys, check the public release identity, representative routes and the critical journey. A monitoring alert or failed public check should have a named response owner. Rolling back page assets may not undo database changes, queued emails or external side effects; keep those changes separately planned and reversible where possible.
Technical examples
Provider-neutral release record
A design example for the evidence a pipeline should retain. Values are illustrative and are not credentials or a runnable workflow.
{
"change_id": "WEB-012",
"source_revision": "<approved-commit>",
"candidate": {
"artifact_digest": "<verified-digest>",
"configuration_profile": "staging-public-v1"
},
"checks": {
"build": "passed",
"routes": "passed",
"enquiry_test": "passed"
},
"staging": {
"release_id": "<staging-release>",
"reviewed_by": "<authorised-reviewer>"
},
"production": {
"approval": "required",
"candidate_artifact": "<promoted-or-rebuilt-artifact>",
"post_release_checks": "required"
},
"rollback_reference": "<previous-working-release>"
}Step-by-step process
Define the release trigger and trusted checks
Specify which approved branch, tag or explicit action creates a candidate and which checks must pass. Restrict changes to release policy itself.
Build and identify the candidate
Record the source revision, dependency lockfile, public configuration profile and artifact digest.
Deploy and review staging
Use isolated data and test recipients. Review the actual candidate URL and save the evidence and unresolved issues.
Approve the production candidate
Confirm whether it is the same artifact or a separately verified build from the same approved revision. Apply the configured release authority.
Deploy with serialisation and recovery
Keep releases separate, avoid overlapping production changes and retain the previous working version.
Check the public result
Verify revision identity and critical pages over HTTPS, then report the actual outcome and the rollback reference.
FOLLOW ONE EXAMPLE
Worked scenario
The homepage fix passes, but the release is not ready
In this fictional example, a contributor changes a headline and the enquiry endpoint. The build succeeds on the CI platform.
- Staging review reveals that the enquiry still targets a test-only endpoint. The candidate remains unapproved despite the successful build.
- The maintainer records the intended public configuration and rebuilds from the approved revision where necessary.
- Relevant form and route checks run against the production candidate before release.
- After deployment, the public marker and enquiry journey are checked. The release record identifies both the artifact and the previous working version.
What this shows: The process distinguishes build success, approval and live success, preventing a plausible preview from being mistaken for a completed release.
The process at a glance
Read Mermaid diagram source
flowchart TD
E[Proposed edit] --> C[Reviewed source revision]
C --> B[Build and trusted checks]
B --> A[Identified artifact]
A --> S[Staging deployment]
S --> R[Stakeholder review]
R --> P{Production authorised}
P -->|No| E
P -->|Yes| D[Serialised production deployment]
D --> H{Public checks pass}
H -->|Yes| L[Record live revision]
H -->|No| F[Respond and restore working release]What you should have at the end
- A release contract linking source, artifact, approval and public evidence.
- A staging and production process with explicit configuration and rollback handling.
Common mistakes and how to avoid them
Assuming the branch name is the safety boundary
Enforce identity, branch and environment rules in the platform; a convention alone cannot restrict access.
Approving one artifact and deploying another without checks
Record rebuild differences and validate the actual production candidate.
Declaring success at upload time
Check the publicly served revision and visitor journey before marking the release live.
APPLY THE IDEA
Try it yourself
Your task: Write the release record for one small website change, including a configuration difference between staging and production.
What to produce: A candidate-to-live sequence and a rollback reference with a named approver.
Check your understanding: Can a reviewer identify exactly what was checked, what was approved and what the public site is serving?
Key terms in plain English
- Artifact
- The built files or packaged application a deployment publishes.
- Digest
- A computed identifier used to check the integrity of an artifact.
- Promotion
- Moving an authorised candidate into a later environment, with its identity and checks recorded.