Jenkins¶

Purpose¶

Jenkins is the Vayzo delivery orchestrator. It is the only supported path for pushing deployable images and promoting them through Kubernetes environments.

For the end-to-end flow and one-time credential inventory, see Fully Automated Delivery.

Agent requirements¶

The Jenkins agent uses label docker and needs:

Docker;
.NET 8 SDK;
Node.js 20+ (22 recommended to match GitHub Actions);
Helm 3;
kubectl;
Git and Bash.

Terraform itself does not have to be installed: scripts/terraform-ci.sh runs the official hashicorp/terraform:1.9 container.

Pipeline modes¶

`ACTION`	Behavior
`Deploy`	CI/CD based on branch/tag
`Rollback`	Helm rollback + automated deployment verification
`Infrastructure`	Terraform plan -> approval -> apply for a selected infrastructure root

Infrastructure exposes INFRA_ENV=platform|staging|production|shared.

Branch/tag behavior¶

Source	Result
Feature/PR	build/test/lint/audit, Terraform/Helm validation, Docker build/scan; no push/deploy
`master`	same gates plus immutable image push
`release/*`	same gates plus automatic staging Terraform reconciliation, Secret sync, Helm deploy and verification
SemVer `v..*`	staging first; then production Terraform plan, one approval, automatic production promotion

Core stages¶

Checkout + metadata
 -> Backend quality gate
 -> Frontend quality gate
 -> Terraform static validation
 -> Helm lint/render
 -> Docker immutable build
 -> Trivy gate
 -> GHCR push
 -> Staging config preflight
 -> Terraform staging plan/apply
 -> Kubernetes Secret sync
 -> Helm staging --atomic
 -> Deployment verification
 -> Release evidence
 -> Production Terraform plan (release tag only)
 -> ONE approval
 -> Terraform production apply
 -> Production Secret sync
 -> Helm production --atomic
 -> Production verification / automatic rollback
 -> Production evidence

Immutable image identity¶

Images are built with the 12-character Git SHA tag:

ghcr.io/thirunk/akshayabazaar-backend:<git-sha>
ghcr.io/thirunk/akshayabazaar-frontend:<git-sha>

Helm receives both image.repository and image.tag explicitly. This is important because the base chart deliberately contains a non-deployable ghcr.io/OWNER/... repository placeholder. No environment deploys a floating latest tag.

Frontend test behavior¶

The current frontend branch does not define an npm test script. Jenkins therefore detects a real test script before running it instead of invoking a nonexistent command. npm run lint, npm run build, and npm audit remain mandatory.

Business/browser tests are the next automation tranche; see the end of Fully Automated Delivery.

Terraform¶

For staging releases Jenkins automatically executes:

scripts/terraform-ci.sh plan staging
scripts/terraform-ci.sh apply staging

Production plan is generated before the approval gate; the saved plan is applied after approval. This prevents the approved plan from being recalculated into a different plan.

Shared/platform infrastructure is changed through ACTION=Infrastructure and gets its own plan/approval/apply flow.

Secret synchronization¶

Jenkins Secret-file credentials are converted into namespace-scoped Kubernetes Secrets using:

scripts/sync-k8s-secrets.sh <namespace> <secret-name> "$APP_ENV_FILE"

The script uses kubectl create secret --from-env-file --dry-run=client | kubectl apply -f -. Secret values are not printed or expanded onto the command line.

Helm migration and rollout¶

Every staging/production deployment uses the existing chart migration hook and:

--wait
--atomic
--history-max 10

The pre-install/pre-upgrade Job invokes the backend with --migrate-only. A migration failure prevents the new application rollout.

Verification and rollback¶

scripts/verify-deployment.sh checks the live Kubernetes state, Services, deployment image tag, in-cluster /health/live, in-cluster /health/ready (DB + Redis), and external frontend/API proxy.

If verification fails after Helm reported a successful rollout, Jenkins automatically attempts helm rollback, verifies the restored revision, archives both verification outputs, and fails the build.

Helm --atomic remains the first rollback layer for rollout/migration failures themselves.

Evidence¶

Successful staging/production runs call scripts/generate-release-evidence.sh. Jenkins archives release identity and verification artifacts without secret values.

Credentials¶

No credential value belongs in this file or in Git. Credential IDs and required environment configuration are listed in Fully Automated Delivery.