CI/CD Deployment Pipeline Basics

A deployment pipeline turns a reviewed commit into a verified release. Keep artifact creation, tests, migration strategy, deployment, health checks, and rollback explicit.

Promote One Release Artifact

• Build or select one immutable release artifact.
• Run checks before promotion.
• Deploy with migration and rollback planning.

Treat Deployment As A Verified Sequence

• Promote to staging.
• Run smoke and health checks.
• Deploy production with release record.

Plan For Migrations And Rollback

• Building separately in each environment introduces drift.
• Migrations can make rollback harder.
• Success exit without health verification is incomplete.

Pipeline Stages

validate -> test -> package -> deploy staging -> smoke test -> approve -> deploy production -> health check -> monitor -> rollback if needed

The pipeline is ready when the same release can be promoted and rolled back predictably. A successful command exit is not enough: health checks and a short observation window should prove that the serving application is healthy.

Continuous Integration, Delivery, And Deployment

The three terms describe different guarantees.

Continuous integration means developers merge small changes frequently and every proposed change is checked against a shared baseline. The checks should be automatic, reproducible, and fast enough that failures receive prompt attention.

Continuous delivery means the main branch remains releasable and a verified artifact can be promoted to production through a controlled decision. Continuous deployment goes further: every qualifying change is promoted automatically without a manual production approval.

A team can practice continuous integration without automatic deployment. It can also have a deployment script without practicing continuous integration if branches remain isolated for weeks and integration failures accumulate.

Build Once And Promote The Same Artifact

The pipeline should identify one source revision and produce one immutable artifact. For a PHP application, that artifact may be a versioned directory, archive, container image, or platform package containing application code and installed production dependencies.

Record:

• source commit;
• artifact digest or immutable version;
• PHP and platform requirements;
• dependency lock-file identity;
• build timestamp;
• pipeline run;
• test results and approvals.

Deploying staging and production from the same artifact removes a major source of drift. Environment-specific configuration and secrets are supplied at runtime; source and dependencies are not rebuilt differently for each environment.

Order Pipeline Stages By Feedback And Risk

Fast deterministic checks should run early:

1. syntax checks;
2. formatting and lint checks;
3. static analysis;
4. focused unit tests;
5. integration and contract tests;
6. artifact construction;
7. deployment to a temporary or staging environment;
8. smoke and migration checks;
9. production promotion;
10. health verification and observation.

Independent checks can run in parallel, but keep failure output understandable. A pipeline that starts fifty noisy jobs and hides the first useful error slows diagnosis.

Flaky tests are defects. Quarantining one temporarily may be necessary, but record an owner and deadline. Blind automatic reruns can turn a genuine intermittent failure into a green pipeline with no investigation.

Credentials And Protected Environments

CI systems execute repository code, including code from proposed changes. Long-lived production credentials in general build jobs create a serious escalation path.

Use short-lived workload identity or narrowly scoped credentials where the platform supports them. Separate build permissions from deployment permissions. Protect production environments with branch rules, required checks, and approvals appropriate to the application's risk.

Untrusted fork builds should not receive secrets. Be careful with workflows that run privileged code from pull requests or load modified pipeline definitions before approval.

Database Migrations In A Pipeline

Application rollback is difficult when the new release applies a destructive schema change first. Use expand-and-contract changes:

1. add new compatible schema;
2. deploy code that can work with old and new forms;
3. backfill and verify data;
4. switch reads or writes;
5. remove old schema in a later release.

Run migrations as an explicit, observable release step. Decide whether one instance, a job, or a deployment controller owns migration execution. Do not let every web replica race to apply the same migration at startup.

Backups do not make every migration instantly reversible. Estimate lock behavior, runtime, disk growth, and rollback implications on production-sized data.

Deployment Success Is Not Application Health

A platform may report that new containers started while every request returns an error. After deployment, verify:

• release identity;
• readiness and health endpoints;
• one critical read path;
• one safe write path where possible;
• queue-worker progress;
• error rate and latency;
• database and cache connectivity;
• business metrics such as successful checkouts.

Use a bounded observation window and explicit thresholds. A smoke test should fail the release when the serving application is unhealthy, not merely print a warning.

Cancellation And Release Concurrency

A pipeline needs a policy for superseded work. If commit B replaces commit A before A reaches production, CI may cancel A's lint or test jobs. It must not interrupt a migration, traffic shift, or infrastructure update halfway through without a recovery plan.

Use concurrency groups or deployment locks to prevent two production releases from changing shared infrastructure simultaneously. Record which commit owns the environment, which jobs were cancelled, and whether an external operation had already begun.

Cancellation policy should differ by stage:

• a queued lint job is disposable;
• a test job can normally be restarted;
• an artifact upload is safe to retry under the same immutable version;
• a migration requires completion, rollback, or reconciliation;
• a traffic shift needs a known serving state;
• an infrastructure update must be checked against the provider's operation status.

Test this policy by starting two releases deliberately. Confirm that the older release cannot overwrite the newer one or leave a partially applied external change.

Rollback And Roll-Forward

Rollback restores a previously verified application artifact, but it may not reverse data changes or external side effects. Define both rollback and roll-forward procedures.

A rollback record should identify:

• the target artifact;
• configuration compatibility;
• schema compatibility;
• queue-message compatibility;
• static-asset compatibility;
• steps to restore traffic;
• checks proving recovery.

Roll-forward is often safer after an irreversible but compatible migration: repair the defect in a new artifact while preserving the new schema. The pipeline should make both paths executable and auditable.

Release Evidence And Auditability

Every production release should answer:

• What changed?
• Who or what approved it?
• Which artifact is serving?
• Which checks passed?
• Which migration ran?
• What happened during health verification?
• Was the release rolled back, superseded, or completed?

Keep this evidence in the delivery system or release records, not in an individual's terminal history. Manual emergency action may still be necessary, but reconcile it into version-controlled automation afterward.

Useful Delivery Metrics

Track metrics that reveal process quality:

• deployment frequency;
• lead time from change to production;
• change failure rate;
• time to restore service;
• pipeline duration;
• flaky-test rate;
• cancelled and superseded runs;
• rollback frequency.

Metrics need context. A high deployment frequency is not success if changes frequently fail, and a low failure rate can be misleading if releases are rare and oversized.

Pipeline Verification Exercise

Exercise the pipeline rather than assuming its YAML is correct:

1. introduce a failing unit test and confirm promotion stops;
2. simulate a missing secret and confirm startup fails clearly;
3. fail a staging smoke test;
4. start two production candidates and verify locking;
5. apply a backward-compatible migration;
6. fail health verification after deployment;
7. execute the documented rollback or roll-forward path;
8. confirm release records identify the final serving artifact.

Run this in a safe environment with production-shaped controls. Recovery steps that have never been exercised are hypotheses.

Coordinate Web, Worker, And Asset Releases

A PHP release often contains more than web request code. Queue workers may continue running the previous version for minutes or hours, scheduled commands may start during deployment, and browsers may retain an older JavaScript bundle. The pipeline must assume that adjacent versions overlap.

Messages crossing that overlap should be backward compatible. Add fields before requiring them, tolerate unknown fields, and avoid changing the meaning of an existing event name in place. Deploy consumers that understand both formats before producers emit the new format. Once old messages have drained and old workers have stopped, a later release can remove compatibility code. Contract tests should deserialize fixtures produced by the previous version and should verify that the old consumer can safely handle messages emitted during the transition when that direction is required.

Static assets need the same discipline. Content-hashed filenames allow a new HTML page and an older cached page to reference different bundles without overwriting one another. Upload assets before routing traffic to HTML that references them, and retain prior bundles long enough for cached pages and rollback. Deleting old assets at the start of deployment turns ordinary cache lifetime into a production failure.

Feature flags can separate code deployment from feature activation, but they are not a substitute for rollback design. Define the default state, owner, expiry date, and behavior when the flag service is unavailable. A kill switch is useful only if operators can identify it, change it safely, and verify the resulting behavior under load.

Canary or blue-green promotion adds a comparison period rather than changing these compatibility rules. Route a controlled share of traffic to the candidate, compare errors, latency, queue behavior, and business outcomes, then promote or stop according to predetermined thresholds. Record which artifact, configuration, migration state, and flag values served each cohort so an apparent regression can be investigated instead of guessed at.

After this lesson, you should be able to distinguish integration, delivery, and deployment; build and promote one immutable artifact; protect credentials and environments; sequence compatible migrations; control concurrent releases; verify application health; and perform an auditable rollback or roll-forward.