Skip to content

CI/CD pipeline plan

This document records the intended pipeline and quality policy. It does not select a CI provider, create repository secrets, or authorize automatic production deployment. GitHub Actions is the likely first implementation because the repository is hosted on GitHub, but the checks should remain ordinary repository commands that can also run locally or in another CI system.

Objectives

  • Give every pull request a repeatable, visible quality result.
  • Keep main deployable from an exact reviewed commit.
  • Build application images once and identify them with immutable commit tags.
  • Make database migrations and production deployment deliberate, observable, and recoverable operations.
  • Prevent CI logs and artifacts from exposing production credentials or Andrea's private information.

Pull-request CI

The first pipeline should run on pull requests and pushes to protected branches. Independent jobs should fail fast where practical and report these gates:

  1. Repository policy: install locked dependencies, validate staged-text/EOL rules, and verify generated or vendored files were not accidentally added.
  2. Lint and type safety: lint portfolio, storefront, and Medusa independently; run framework type checks where lint does not already cover them.
  3. Tests: run portfolio rendering tests, storefront unit/API tests, backend unit tests, and deployment-tool tests.
  4. Production builds: build all three applications with non-secret CI configuration so development-only behavior cannot hide a production failure.
  5. Container contract: build the production images, render the production Compose configuration, start an isolated stack when resources permit, and exercise health endpoints.
  6. Migration rehearsal: start a disposable PostgreSQL/Redis environment, migrate an empty database, optionally restore a sanitized fixture, migrate it, and run commerce-foundation verification. Never point CI at the VPS database.
  7. Security and dependency review: audit production dependencies, scan images and committed secrets, and report actionable findings under a documented severity policy.

Required checks should be branch-protection gates. Direct pushes to main should be disabled once the pipeline is trusted, while emergency access and its audit expectations are documented separately.

Linting policy

Lint errors always fail CI. Warnings must remain visible and must not silently grow. The initial pipeline should record the known warning baseline per application and fail when a change introduces additional warnings. Existing warnings should have tracked cleanup work rather than being hidden with broad disable comments.

After the current portfolio image warnings are resolved or deliberately replaced by narrow reviewed exceptions, each application should run with zero warnings allowed (for ESLint, the equivalent of --max-warnings=0). CI and the local pre-commit hook should call the same package scripts so developers do not discover a different lint policy only after pushing.

Generated output, third-party bundles, build directories, and framework caches should be excluded explicitly. Source directories must not be excluded merely to make the gate pass. Formatter enforcement can be a separate deterministic check; CI should report formatting differences without rewriting a contributor's branch.

Continuous delivery

A successful commit on main may produce versioned application images and a release manifest containing the Git commit, image digests, dependency-lock hash, and migration set. Publishing an artifact is not the same as deploying it.

The delivery workflow should:

  1. run the repository's change-aware deployment planner;
  2. retain its exact proposed target and commit as a reviewable artifact;
  3. require a protected-environment approval before production;
  4. verify a recent database and media backup before a stateful change;
  5. deploy only the planned portfolio, storefront, Medusa, or all-apps target;
  6. run migrations only when explicitly planned and approved;
  7. execute internal and public smoke tests;
  8. record the deployed per-service commits, image digests, migration result, and health result as a deployment event;
  9. stop and present the known-good rollback command when acceptance fails.

The pipeline must not modify DNS, Nginx, Let's Encrypt, VPS firewall rules, or persistent volumes unless a separately reviewed infrastructure workflow is later introduced. Database rollback is not inferred from application rollback.

Secrets and environments

  • CI uses disposable test credentials and synthetic data.
  • Production secrets live in the CI provider's protected environment or remain exclusively in the VPS private environment file; they are never committed.
  • SSH credentials receive the narrowest practical access, use host-key pinning, and are available only to approved production jobs.
  • Forked pull requests and untrusted code never receive deployment, registry-write, payment, email, analytics, or production database credentials.
  • Logs and uploaded artifacts are reviewed for URLs, tokens, customer data, and environment dumps before retention is enabled.

Implementation stages

  1. Add provider workflow files for repository policy, lint, existing tests, builds, deployment-tool tests, dependency caching, and result summaries.
  2. Add branch protection after the required checks are stable and reasonably fast.
  3. Add disposable service integration and migration-rehearsal jobs.
  4. Publish commit-tagged images to the selected private registry and retain SBOM and vulnerability reports.
  5. Connect the existing deployment planner to a manually approved staging or disposable environment.
  6. Add protected production delivery only after backups, rollback, observability, and environment ownership have been tested.
  7. Revisit parallelism, caching, artifact retention, scheduled dependency scans, and cost after observing real pipeline duration and failure patterns.

Provider selection, exact workflow syntax, registry choice, warning-baseline mechanics, integration-test fixtures, and production approval roles remain future implementation decisions.