57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
|
# Quickstart: Validating the CI Pipeline
|
||
|
|
|
||
|
|
Prerequisites: a Jenkins instance with the `Jenkinsfile` (to be added at repo root by the
|
||
|
|
implementation) registered as a Multibranch Pipeline job pointed at this repository, with
|
||
|
|
credentials configured for `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `JWT_SECRET`, AWS keys, and a
|
||
|
|
container registry, per `research.md`'s secrets-handling decision.
|
||
|
|
|
||
|
|
## Scenario 1 — a bad change is caught and blocked (User Story 1)
|
||
|
|
|
||
|
|
1. On a feature branch, introduce a deliberate failure, e.g. add a lint violation to any file
|
||
|
|
under `src/`.
|
||
|
|
2. Push the branch / open a PR.
|
||
|
|
3. **Expected**: the pipeline job triggers automatically (FR-001), runs
|
||
|
|
`Checkout → Install → Environment validation → Typecheck` (pass) `→ Lint` (fail), then stops —
|
||
|
|
no `Unit test`/`Build`/`Publish`/`Deploy` stage runs (FR-003, FR-005).
|
||
|
|
4. **Expected**: the Jenkins build result shows the `Lint` stage as failed, with the ESLint output
|
||
|
|
visible directly in the stage log — no local reproduction needed to see why it failed
|
||
|
|
(FR-004, SC-002).
|
||
|
|
5. Revert the violation, push again. **Expected**: all stages through `Docker build` pass.
|
||
|
|
|
||
|
|
## Scenario 2 — environment misconfiguration fails fast (Edge Case)
|
||
|
|
|
||
|
|
1. Temporarily remove/rename a required variable from the credentials injected for a test run
|
||
|
|
(e.g. `DATABASE_URL`).
|
||
|
|
2. Trigger a run.
|
||
|
|
3. **Expected**: the `Environment validation` stage fails immediately, before `Typecheck`/`Unit
|
||
|
|
test`, with the same descriptive error `src/config/env.ts`'s Zod schema already produces
|
||
|
|
(FR-002).
|
||
|
|
|
||
|
|
## Scenario 3 — a validated change deploys without manual steps (User Story 2)
|
||
|
|
|
||
|
|
1. Merge a clean change into the branch mapped to the `test` Deploy Target.
|
||
|
|
2. **Expected**: the pipeline runs every validation stage, then `Build → Docker build → Publish →
|
||
|
|
Deploy`, and the `test` environment is running the new image afterward — with no engineer
|
||
|
|
running a deploy command by hand (FR-007, SC-003).
|
||
|
|
3. Inspect the deploy stage's credential usage: confirm no step reads `.env.test`/`.env.prod`
|
||
|
|
from the repository checkout — only from the CI system's injected credentials (FR-008, SC-004).
|
||
|
|
|
||
|
|
## Scenario 4 — a validate-only run never deploys (Edge Case)
|
||
|
|
|
||
|
|
1. Push a commit to a branch with no configured Deploy Target (e.g. a random feature branch).
|
||
|
|
2. **Expected**: all stages through `Docker build` run and pass; `Publish`/`Deploy` are skipped,
|
||
|
|
not attempted and not marked as failed.
|
||
|
|
|
||
|
|
## Scenario 5 — concurrent runs don't interfere (Edge Case)
|
||
|
|
|
||
|
|
1. Trigger two pipeline runs at the same time (e.g. push to two different branches, or re-run the
|
||
|
|
same job twice back to back).
|
||
|
|
2. **Expected**: each run gets its own workspace and Compose project name; one run's test database
|
||
|
|
state or build artifact never appears in or affects the other (FR-009, SC-005).
|
||
|
|
|
||
|
|
## What "done" looks like
|
||
|
|
|
||
|
|
All five scenarios above pass, and `specs/001-ci-pipeline/checklists/requirements.md` plus this
|
||
|
|
quickstart together demonstrate every functional requirement and success criterion in `spec.md`
|
||
|
|
without needing to read the `Jenkinsfile` itself to know what "correct" means.
|