Prerequisites

These are one-time setup steps that must be completed before deploying any environment or region.

---

1 GitHub App: cogrion-platform-deploy

A single GitHub App is used for all CI/CD access to platform repositories.

Field	Value
Github App name	cogrion-platform-deploy
Homepage URL	https://app.cogrion.com
Webhook	DISABLED
Owner	sparqd organisation

1.1 Repository permissions

Repository	Permission	Purpose
cogrion-terraform	Contents: Read	Read infrastructure config in pipelines
cogrion-gitops	Contents: Read + Write	ArgoCD pulls manifests; CI pushes image tag updates

1.2 Setup

1. Go to GitHub → Organisation Settings → Developer Settings → GitHub Apps → New GitHub App

2. Set name to cogrion-platform-deploy, disable Webhook

3. Under Repository permissions set Contents as above

4. Under Where can this GitHub App be installed select Only on this account

5. Create the app, then go to Install App tab → click Install next to sparqd → on the install screen select Only select repositories → add cogrion-terraform and cogrion-gitops

6. To add or remove repositories later: Organisation Settings → Installed GitHub Apps → cogrion-platform-deploy → Configure → Repository access

7. Generate a private key:

   • On the app settings page scroll down to Private keys → Generate a private key
   • GitHub downloads a .pem file (e.g. cogrion-platform-deploy.2026-05-28.private-key.pem)
   • Keep this file — it is shown only once and cannot be re-downloaded
   • Store it in AWS Secrets Manager:

   cogrion/shared/github-app/cogrion-platform-deploy

   With properties:

   Property	Where to find it	Maps to ArgoCD field
   appId	App settings page → App ID	githubAppID
   installationId	URL after installing: .../installations/{id}	githubAppInstallationID
   privateKey	Generated private key PEM (newlines escaped as \n)	githubAppPrivateKey

1.3 Usage

N/A

---

2 Populating AWS Secrets Manager

Secrets are created as empty shells by Terraform. Values must be populated manually before bootstrapping any cluster.

2.1 cogrion/shared/github-app/cogrion-platform-deploy

1. Open AWS Console → Secrets Manager → cogrion/shared/github-app/cogrion-platform-deploy

2. Click Retrieve secret value → Edit

3. Switch to the Plaintext tab and paste the following JSON:

   {
     "appId": "123456",
     "installationId": "78901234",
     "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----"
   }

   privateKey must have newlines escaped as \n. To convert from a PEM file:

   awk 'NR==1{printf "%s", $0} NR>1{printf "\\n%s", $0} END{print ""}' cogrion-platform-deploy.pem

4. Click Save

---

3 Creating Regional Subdomain

3.1 Creating Subdomain in AWS Route 53

3.1.1 Create the (env).(region).cogrion.com Hosted Zone

1. Go to AWS Console → Route53 → Hosted zones
2. Click Create hosted zone
3. Fill in:
   • Domain name: (env).(region).cogrion.com
   • Type: Public hosted zone
4. Click Create hosted zone
5. You'll see 4 NS records — copy all 4 values, you'll need them next

3.1.2 — Add NS Delegation in the cogrion.com DNS

This part assume cogrion.com is managed on AWS Route 53. Practically this should be managed in GoDaddy or Cloudflare.

1. Still in Route53 → Hosted zones
2. Click on cogrion.com
3. Click Create record
4. Fill in:
   • Record name: test
   • Record type: NS
   • TTL: 300
   • Value: paste the 4 NS values from Step 1, one per line
5. Click Create records

3.1.3 — Request ACM Certificate

1. Go to AWS Console → ACM → Request
2. Select Request a public certificate → Next
3. Add domain names:

   (env).(region).cogrion.com
   *.(env).(region).cogrion.com

4. Validation method: DNS validation
5. Click Request

3.1.4 — Validate the Certificate

1. Click into the pending cert
2. Under Domains → click Create records in Route53
3. ACM automatically adds the CNAME validation records into your (env).(region).cogrion.com hosted zone
4. Click on Create records.
5. Wait 2–5 minutes → status changes to Issued

3.1.5 — Use on Ingress annotation

Usage with AWS Load Balancer Controller:

alb.ingress.kubernetes.io/certificate-arn: "arn:aws:acm:ap-southeast-1:<account_id>:certificate/<new-cert-id>"

---