add-app-deployment

Add App Deployment

Add full deployment pipeline support for a new application in the Resal GitOps infrastructure.

Infrastructure Overview

The infrastructure uses:

• ArgoCD for GitOps deployment orchestration
• Helm for Kubernetes manifests (standardized templates)
• Terraform for AWS infrastructure (ECR repositories)
• GitHub Actions reusable workflows for CI/CD
• 1Password operator for secrets management
• AWS ALB ingress controller for routing

See references/infrastructure-conventions.md for full details on repo structure, naming conventions, and patterns.

Repository Setup

The infrastructure repo must be available locally to make changes. If it's not already cloned or available as a working directory, clone it:

git clone https://github.com/ResalApps/infrastructure.git

• Infrastructure repo: https://github.com/ResalApps/infrastructure.git (GitHub org: ResalApps)
• Default branch: main
• All app repos also live under https://github.com/ResalApps/

Before starting, check if the infrastructure repo is already available:

1. Check if the user has it open as a working directory
2. Check common local paths (e.g., sibling directories of the current project)
3. If not found, clone it to a suitable location and inform the user

Workflow

Phase 1: Gather Information

Before creating any files, collect these required inputs from the user:

1. App name - Kubernetes-friendly name (e.g., store-frontend, payment-ms)
2. Namespace - Which namespace group (e.g., core, resal-app, business-solutions, merchant-solutions, resal-admin)
3. ECR repository path - Format: {namespace}/{app-name} (e.g., resal-app/resal-store-frontend)
4. GitHub repo name - The ResalApps GitHub repository name
5. Ingress hostnames - Dev and stage URLs (e.g., app-dev.myresal.com, app-stg.myresal.com)
6. Container port - Port the app listens on (default: 8080 for backends, 3000 for frontends)
7. Component type - backend, frontend, api, etc.
8. ConfigMap data - Runtime environment variables needed
9. 1Password secrets - Any secrets to pull from 1Password vaults
10. Resources - CPU/memory requests (default: 100m/128Mi)
11. CI branch strategy - Which branches trigger dev/stage builds (default: develop/stage)
12. Build args - Any Docker build arguments needed (common for Next.js frontends with NEXT_PUBLIC_* vars)

Phase 2: Create Implementation Plan

Use the checklist in references/deployment-checklist.md to generate a concrete plan. Each item maps to specific files that must be created or modified.

Phase 3: Execute

For each item in the checklist, use the templates and patterns from:

• references/helm-templates.md - Helm templates, values/config file structures, Bitnami image guidance
• references/workflow-templates.md - GitHub Actions workflow templates

Key rules:

• All Helm template helper names must use the app name: {app-name}.name, {app-name}.labels, etc.
• Template files start with # Code generated by update-resal-apps-templates; DO NOT EDIT.
• Image tags follow the pattern {env}.1.1.{run_number}
• ECR image repository format: 882222437772.dkr.ecr.us-east-2.amazonaws.com/{namespace}/{app-name}
• Dev 1Password vault: dev-cluster, Stage: stage-cluster
• Dev ACM cert ARN (auto-selected): arn:aws:acm:us-east-2:244122818208:certificate/17a0e0c3-32f5-4718-b66a-88cc06fd7b2c
• App repo helm configs go in helm/{app-name}/config-{env}.yaml (nested, not flat)
• Build workflows must always pass helm_values_file input
• Bitnami images: use bitnamilegacy/ registry (not bitnami/) — see helm-templates.md for details
• Reusable workflows must be referenced as @main (not pinned SHA)

Phase 4: Verify

After implementation, run these checks:

1. Verify complete file structure exists under apps/{namespace}/{app-name}/
2. Grep for any stale/wrong references (e.g., copied from another app)
3. Verify ArgoCD entries exist in both app-of-apps/values-dev.yaml and values-stage.yaml
4. Verify ECR entry exists in terraform/common/main.tf
5. Verify CI workflows reference the correct ECR repo, app name, and namespace

Phase 5: Commit & PR

Create a branch feat/add-{app-name}-deployment in each repo that has changes, commit, and create PRs.

Infrastructure repo: Push branch and create PR against main at ResalApps/infrastructure. App repo: Push branch and create PR against main (or the app's default branch).

Deployment order after merge:

1. Terraform apply in common-infrastructure workspace (creates ECR)
2. Merge infrastructure PR (ArgoCD discovers new app)
3. Merge app repo PR (CI pushes first image)
4. ArgoCD syncs and deploys