saqib mirandClaude Sonnet 5
414f336704
/speckit-specify + /speckit-plan output for 001-ci-pipeline: feature spec with 2 user stories and 10 functional requirements, requirements quality checklist, implementation plan with constitution gate check, Phase 0 research (6 decisions incl. secrets-from-credentials-store), Phase 1 data model, pipeline stage contract, and a 5-scenario quickstart validation guide. No Jenkinsfile yet — that's the implementation step after /speckit-tasks. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
|