Skip to content

Deployments

Last audited: 2026-07-21.

This guide summarizes how MamNajem changes move through shared environments.

Branch Policy

Long-lived backend and architecture branches:

  • integration
  • production

Backend and architecture changes should be pushed to integration. Production changes are manual and user-controlled.

The customer web repository also uses integration and production as its long-lived environment branches. Production promotion remains fast-forward-only and user-controlled.

Keep history linear:

  • Fetch and prune before syncing branches.
  • Use git pull --ff-only.
  • Use fast-forward-only promotion.
  • Do not create merge commits.
  • Do not push directly to production.

Before any production rollout, verify production has no commits absent from integration. Use the release worktree checklist for the exact per-repository commands and stop conditions.

Integration Host

Since 2026-11-08 integration no longer runs on AWS. The Lightsail backend host and the Amplify integration apps are retired; integration runs on the integration laptop behind a Cloudflare tunnel. Production is unchanged.

Surface Integration URL
API (/v1, webhooks, actuator) https://api.mamnajem.win
Customer web (landing-frontend) https://www.mamnajem.win
Admin (web-admin) https://admin.mamnajem.win
Docs https://docs.mamnajem.win
Web app (web-frontend) https://app.mamnajem.win
Cognito hosted UI https://auth-integration.mamnajem.pl (unchanged, AWS)

GitLab cannot reach the laptop, so nothing pushes to it. A deployer on the laptop polls GitLab for each repository's newest successful build job on integration, downloads that job's artifacts and deploys them: the backend JAR with APP_VERSION set to the commit, static sites by atomic directory swap. Integration pipelines keep their build jobs and artifacts; instead of deploying, a bounded verification job (about 20 minutes) waits until the integration URL serves the pushed commit: the backend's deployed version, or a static site's build marker.

Backend

The backend uses GitLab CI/CD.

Common pipeline areas:

  • Maven verify.
  • Dependency check.
  • Gitleaks.
  • Semgrep.
  • OpenAPI compatibility checks.
  • Scheduled E2E suites.
  • Integration live-version verification.
  • Production deploy verification.

Integration deploy shape:

  1. GitLab builds the backend JAR as a job artifact.
  2. The integration laptop deployer downloads the newest successful build artifact on integration into /opt/mamnajem-integration/releases/<sha>/.
  3. The current symlink is updated and APP_VERSION is set to the commit.
  4. The backend container is recreated and must become ready on /actuator/health/readiness; otherwise the deployer rolls back.
  5. The integration pipeline waits, bounded, until https://api.mamnajem.win reports the pushed version.

Production deploy shape:

  1. Backend image/JAR changes pass CI.
  2. ECS service deployment is triggered.
  3. ALB target health and /actuator/health verify runtime readiness.
  4. New Relic conditions watch for health, 5xx, CPU, and target issues; CloudWatch logs corroborate failures.

Mobile Frontend

The mobile app uses GitLab dispatcher pipelines on integration and production.

Common checks:

  • Lint.
  • TypeScript.
  • Prettier.
  • Jest.
  • CI helper tests.
  • Build configuration assertions.
  • New Relic release/dist assertions.
  • Firebase config assertions.

Android release flow:

  1. Build Android release artifact.
  2. Upload to Google Play internal.
  3. Promote to closed alpha through GitLab OIDC and Google Workload Identity Federation.
  4. For integration, publish the Android required-app-update Remote Config after alpha upload.
  5. For production, the production-track upload is a manual job that promotes from alpha.

iOS release flow:

  1. Generate native iOS project.
  2. Install pods.
  3. Build archive.
  4. Upload IPA to TestFlight.
  5. The iOS child pipeline runs for integration and production parent pipelines.

The mobile repository does not contain the customer Amplify hosting build. A mobile push cannot trigger or publish the customer website.

Customer Web

The landing-frontend repository owns the marketing, legal, support, public intake, native bridge, and mobile association-file surface. The production customer website is hosted by the retained production AWS Amplify application; the integration site is served by the integration laptop at https://www.mamnajem.win. It does not provide Cognito sign-in or the authenticated product.

Integration deployment:

  1. Push a completed change to landing-frontend integration.
  2. GitLab runs validation, browser smoke checks and the static build.
  3. The integration laptop pulls the newest successful build artifact.
  4. The pipeline waits, bounded, until https://www.mamnajem.win serves the pushed commit's build marker.

The production customer Amplify branch has enableAutoBuild=false; GitLab is the deployment trigger. There is no scheduled customer-web rebuild.

Production does not auto-build. Promote the already verified integration commit to production using the fast-forward-only policy, then run the user-controlled manual production deployment job. Never publish production from a mobile push.

After a customer-web deployment, verify:

  • /.well-known/assetlinks.json, /.well-known/apple-app-site-association, and /apple-app-site-association are valid and served with the expected content types.
  • Native bridge routes preserve their query strings and fragments for /open and /account/payment, plus supported property, lease, invitation and bank-transfer payment destinations. Stripe checkout, Connect and hosted subscription/rent-payment return targets are unavailable; association paths include only password recovery and invitation acceptance.
  • Marketing, legal, support, and public intake pages load without exposing an authenticated customer product.

The backend verifies Turnstile tokens submitted by public forms. The integration Turnstile secret is supplied by protected GitLab CI/CD variables during deploy; the production secret is sourced from AWS Secrets Manager.

Web App

The web-frontend repository is the React/Vite customer web app. It has an integration deployment only, at https://app.mamnajem.win (OAuth origin https://app.mamnajem.win, API https://api.mamnajem.win/v1); it is not part of the client contract and has no production deployment.

web:build:integration builds the static SPA for integration, writes the build marker dist/.mamnajem-build.json and keeps dist/ as a one-week artifact. The integration laptop serves the newest successful artifact with an index.html fallback for client routes. web:verify:integration waits up to 20 minutes for https://app.mamnajem.win/.mamnajem-build.json to report the pushed commit.

Documentation Site

The docs repository builds a static MkDocs site, but it is not published by GitLab Pages and no Amplify app is connected to the repository. Integration docs are served by the integration laptop at https://docs.mamnajem.win. Terraform owns the production manual-deployment Amplify application, branch, headers, cache policy, and custom-domain activation for https://docs.mamnajem.pl.

The normal docs:build job performs one strict MkDocs build, creates the canonical build marker public/.mamnajem-build.json and deterministic ZIP, and runs verify-docs-deployment-artifact.py. The verifier checks both SHA-256 sidecars, exact ZIP membership and bytes, normalized metadata, and every local HTML link before the residual scanner runs over public/. The job publishes public/ and the verified ZIP only as private pipeline artifacts and does not start an Amplify deployment.

On integration pushes, the integration laptop pulls the newest successful docs:build artifact and serves public/. verify_integration_docs uses no credentials: scripts/wait-for-docs-build-marker.py polls https://docs.mamnajem.win/.mamnajem-build.json for up to 20 minutes, without following redirects, until its repository is mamnajem/docs and its candidateSha is the pushed commit.

The only docs deploy job is deploy_production_docs. It is manual and uses GitLab OIDC with the AWS STS audience. Its rules accept only the protected production branch and a fresh request whose SHA equals CI_COMMIT_SHA; durable activation variables are never used in job rules.

Create the requested pipeline with activation_requested="true" and activation_request_sha="<full candidate SHA>" in the GitLab pipeline inputs (inputs in POST /projects/:id/pipeline). The request flag accepts only the strings false and true; the SHA accepts only an empty default or 40 lowercase hexadecimal characters. Ordinary push pipelines default to no deployment. Inputs avoid pipeline-variable override restrictions and do not grant deployment authority: protected activation, sealed-contract and exact-artifact checks below still apply. Do not lower the project's pipeline-variable permission policy.

The production job no longer has a reset-controller preflight: the controller lived on the retired Lightsail integration host, and the owner chose on 12 November 2026 to drop the check rather than re-home it. After an activation run, set MAMNAJEM_ACTIVATION_REQUESTED back to false and clear MAMNAJEM_ACTIVATION_REQUEST_SHA by hand. The job's after-script still calls scripts/reset-docs-activation.sh, which reports that no controller answers; an after-script failure does not fail the deployment.

Before credentials are requested, the manual job requires all of the following:

  1. The protected production environment has MAMNAJEM_ACTIVATION_ENABLED=true.
  2. MAMNAJEM_ACTIVATION_SHA, MAMNAJEM_ACTIVATION_REQUEST_SHA, and the only release-matrix variable, MAMNAJEM_SEALED_RELEASE_MATRIX_SHA, all equal the checked-out CI_COMMIT_SHA.
  3. It resolves only MAMNAJEM_PRODUCTION_ARCHITECTURE_CONTRACT_FILE with MAMNAJEM_PRODUCTION_ARCHITECTURE_CONTRACT_SHA256.
  4. The protected F9 architecture-contract file exists, its SHA-256 matches, and its production docs entry provides the matching app ID, literal branch, deployment role ARN, and candidate SHA.

The source contains no provider IDs, role ARNs, repository connection, webhook, deploy token, or static AWS key. A missing, stale, cross-environment, or placeholder F9 contract fails before OIDC. Once F9 supplies the values, the job may use only Amplify CreateDeployment, StartDeployment, GetJob, and StopJob for the manual ZIP deployment. The AWS token is materialized in a mode-0600 temporary file, ambient credential sources are disabled, and the exact assumed role ARN is checked before deployment. Upload and job polling are bounded; unknown or timed-out states stop the Amplify job. A successful provider job is not accepted until the live environment serves the matching build marker. The independent after_script controller resets the matching activation flag and then clears its activation SHA for success, failure, or cancellation.

Do not create a docs deployment or bind a custom domain from this repository. Task 11 is the first coordinated activation; it must verify the deployed build marker, ZIP checksum, routes, assets, browser console, and Terraform-owned header set.

Admin Web

The admin web app is a Vite + React app using AWS Amplify libraries with the Cognito admin pool. Production admin hosting stays on its Amplify application.

Integration hosting:

  • Host: the integration laptop
  • Domain: https://admin.mamnajem.win
  • Repository: https://gitlab.com/mamnajem/web-admin

The web-admin GitLab pipeline validates tests, audit, and build output. The integration laptop pulls the newest successful integration build artifact, and the pipeline waits until the admin site serves the pushed commit's build marker. After a web-admin push, check the GitLab pipeline for that commit, then smoke the deployed admin shell. Without an admin session, the minimum smoke is:

  1. Open https://admin.mamnajem.win/#founding-pilot.
  2. Confirm the admin sign-in shell loads.
  3. Confirm the protected admin API returns 401 when unauthenticated.
  4. Confirm the loaded /assets/index-*.js bundle contains the released UI strings or controls.

Check:

  • VITE_COGNITO_ADMIN_USER_POOL_ID
  • VITE_COGNITO_ADMIN_CLIENT_ID
  • Admin user pool membership and groups.
  • Backend admin authorization.

Architecture

Terraform is the normal mutation path for shared infrastructure.

Areas:

  • terraform/aws-integration
  • terraform/aws-production
  • terraform/google
  • terraform/gitlab
  • shared Terraform modules

Expected safe checks:

terraform fmt -recursive -check
./scripts/tf.sh all-validate

Do not run terraform apply unless the change is explicitly approved for the target environment.

Website association inputs

Integration and production static builds require MAMNAJEM_STAGING_CLIENT_CONTRACT_FILE (contract JSON), MAMNAJEM_STAGING_CLIENT_CONTRACT_SHA256 (lowercase file SHA-256), and ANDROID_CERT_SHA256_FINGERPRINTS_JSON (canonical uppercase Play signing fingerprints).

While an environment's signing contract is unavailable, MAMNAJEM_ASSOCIATIONS_PENDING=true permits its public/legal pages to build without assetlinks.json or apple-app-site-association. The verifier rejects these files if present in pending mode. Pending mode is allowed only for integration/production; a supplied contract must match the build's NEXT_PUBLIC_APP_ENV.

Remove the pending variable and redeploy per environment once its contract and signing fingerprints exist. App-link association verification is required then; deep links remain unavailable while pending. Do not borrow another environment's contract.

Push verification

After pushing changes:

  1. Watch the GitLab pipeline to a terminal state.
  2. If it fails, identify the failing job.
  3. Classify the failure:
  4. Application.
  5. Test.
  6. Contract.
  7. Security.
  8. Deploy.
  9. Infrastructure.
  10. Report the result and the next required action.