Run 1: Infrastructure — Completion Report

Date: 2026-03-19 Status: Complete (one deferral) PR: infrastructure#425

Exit Criteria Results

#	Criterion	Status	Value
1	demo branch exists in arda-frontend-app	Pass	Created off main at 30f4e73
2	amplifyBranch.cfn.yaml validates	Pass	CI passed on PR1
3	amplifyExports.cfn.yaml validates	Pass	CI passed on PR1
4	Kyle auto-build unchanged	Pass	Verified via amm.sh SandboxKyle002 kyle
5	Demo Amplify stacks deployed	Pass	Alpha001-demo-Amplify, Alpha001-demo-AmplifyBranch
6	Demo auto-build disabled	Pass	enableAutoBuild: false
7	CloudFormation export: AmplifyAppId	Pass	d2jmcx9om9gokx
8	CloudFormation export: AmplifyBranchName	Pass	demo
9	IAM role (Alpha001)	Pass	Alpha001-API-GitHubActionFrontEnd
10	IAM role (Alpha002)	Pass	Alpha002-API-GitHubActionFrontEnd
11	OIDC assumption works	Deferred	See Deferred: OIDC Test
12	Demo site loads	Pass	https://demo.d2jmcx9om9gokx.amplifyapp.com returns 200
13	PR1 merged	Pass	infrastructure#425

Artifacts Produced

Artifact	Location
demo branch	arda-frontend-app repo
Demo Amplify App ID	d2jmcx9om9gokx (us-east-1)
CloudFormation exports	Alpha001-demo-I-AmplifyAppId, Alpha001-demo-I-AmplifyBranchName
IAM role (Alpha001)	Alpha001-API-GitHubActionFrontEnd
IAM role (Alpha002)	Alpha002-API-GitHubActionFrontEnd
amplifyExports.cfn.yaml	infrastructure/src/main/cfn/amplifyExports.cfn.yaml
amm.sh with mappings	infrastructure/amm.sh
test-oidc.yaml (temporary)	arda-frontend-app/.github/workflows/test-oidc.yaml on demo branch

Deferred: OIDC Test

The test-oidc.yaml workflow was pushed to the demo branch, but GitHub Actions workflow_dispatch requires the workflow file to exist on the default branch (main) for it to be discoverable and triggerable via the UI or API. Since test-oidc.yaml is only on demo, it cannot be dispatched.

Impact: Low. The OIDC assumption will be validated naturally in Run 2 when deploy.yaml (also on demo) triggers and assumes the role. The IAM role exists and its trust policy was validated by npx cdk synth in CI.

Action for Run 2: The first deploy.yaml trigger is the de facto OIDC test. If it fails with an OIDC error, the IAM role trust conditions need debugging before proceeding.

Issues Encountered

1. AMPLIFY_GITHUB_ACCESSTOKEN PAT permissions (blocking, resolved)

The fine-grained PAT (Amplify_GitHub_AccessToken) stored in 1Password and GitHub secrets did not have access to arda-frontend-app. It was originally scoped for kyle-frontend-app only.

Symptoms: CloudFormation CREATE_FAILED on AmplifyApp with 404 Not Found on list-repository-webhooks.

Root cause: Fine-grained PATs require explicit repository content access. Without “Contents: read” permission for the repo, all API endpoints return 404 (not just content endpoints).

Fix: Added “Contents: Read-only” permission to the PAT for all org repos.

Second failure: After fixing permissions, the enterprise policy rejected the token because it had no expiration date. Error: The 'Arda Systems' enterprise forbids access via a fine-grained personal access tokens if the token's lifetime is greater than 366 days.

Fix: Regenerated the PAT with an expiration within 366 days. Updated the value in 1Password (Arda-SystemsOAM/Amplify_GitHub_AccessToken).

Action for Run 4: The AMPLIFY_GITHUB_ACCESSTOKEN GitHub secret in the infrastructure repo must also be updated with the new regenerated token value before running amm.yml workflows. The current secret has the old (invalidated) token.

2. GITHUB_TOKEN for GitHub Packages (blocking, resolved with workaround)

The amplify.cfn.yaml CloudFormation template does not include a GITHUB_TOKEN environment variable. The frontend app requires this token to authenticate with GitHub Packages for the @arda-cards/design-system private package.

Symptom: Amplify build failed with npm error 401 Unauthorized on @arda-cards/design-system.

Workaround: Manually added GITHUB_TOKEN to the demo Amplify app via aws amplify update-app --environment-variables. The token comes from 1Password: Arda-SystemsOAM/GPR-Read token (credential field).

Complication: The update-app --environment-variables API replaces all environment variables rather than merging. The first update-app call overwrote the 16 CloudFormation-managed env vars with just GITHUB_TOKEN. Required re-deploying the CloudFormation stack to restore them, then using a merge approach (get existing vars via API, append GITHUB_TOKEN, update with full set).

Ticket: infrastructure#427 — proper fix to add GITHUB_TOKEN to the CloudFormation template.

Action for Run 4: The existing dev, stage, and prod apps already have GITHUB_TOKEN set manually. The workaround only applies to newly created apps (demo, future partitions). Any CloudFormation stack update to existing apps that triggers an Amplify app resource update could overwrite manually-set env vars — monitor this during cutover.

3. aws amplify update-app --environment-variables replaces, not merges

Discovered that the AWS CLI amplify update-app --environment-variables flag completely replaces the environment variables map rather than merging with existing values. This is an AWS API behavior, not a bug.

Safe pattern for adding env vars:

# Get existing vars
EXISTING=$(aws amplify get-app --app-id {id} --query "app.environmentVariables" --output json)
# Merge with new var
MERGED=$(echo "${EXISTING}" | jq --arg val "new_value" '. + {"NEW_VAR": $val}')
# Update with full set
aws amplify update-app --app-id {id} --environment-variables "${MERGED}"

Action for all runs: Never call update-app --environment-variables with a partial set. Always merge first.

4. Local amm.sh secret routing (non-blocking, ticketed)

The 1Password fallback in amm.sh hardcodes Kyle-specific vault paths for ARDA_API_KEY. Running locally for non-Kyle partitions requires an explicit override: export ARDA_API_KEY="$(op read 'op://Arda-DemoOAM/ARDA-API-KEY/password')".

Ticket: infrastructure#426

Action for local runs: Always override ARDA_API_KEY when running amm.sh for non-Kyle partitions.

5. AWS profile region mismatch (non-blocking)

The Admin-SandboxKyle002 profile defaults to us-east-2 but Kyle’s infrastructure is in us-east-1. Running amm.sh without --region us-east-1 fails at aws eks describe-cluster.

Action for local runs: Always pass --region us-east-1 for Kyle deployments.

6. Custom domain propagation

The demo site is accessible at the Amplify default URL (https://demo.d2jmcx9om9gokx.amplifyapp.com) but demo.alpha001.app.arda.cards may need time for DNS/domain association to propagate.

Action for Run 2: Use the Amplify URL for initial verification. Check demo.alpha001.app.arda.cards before starting validation in Run 3.

Guidance for Subsequent Runs

Run 2 (Workflows)

1. OIDC will be tested naturally: The first deploy.yaml trigger is the OIDC test. If it fails, check the IAM role trust policy for the demo branch condition.
2. Delete test-oidc.yaml from the demo branch as planned (Task 2.5).
3. workflow_dispatch on demo branch: GitHub Actions workflow_dispatch requires the workflow file on the default branch to be triggerable via UI/API. However, the workflows ARE triggerable if you push them to demo AND there is a matching workflow file on main. Since these are new workflows that don’t exist on main, you may need to trigger them via a push event or find an alternative. Investigate this before writing the workflows — if workflow_dispatch doesn’t work from demo, use push trigger during development.

Run 4 (Cutover)

1. Update AMPLIFY_GITHUB_ACCESSTOKEN GitHub secret before running amm.yml workflows. The current secret has the old (invalidated) PAT.
2. GITHUB_TOKEN env var: Existing apps have it manually. New apps from the template don’t. Monitor for any CloudFormation updates that might overwrite env vars on existing apps.
3. aws amplify update-app: Always use the merge pattern when modifying env vars.
4. Prod region: Prod Amplify is in us-east-2. CloudFormation export stacks go to us-east-1. The amplify_region override is needed for prod in the workflow matrix.
5. Local amm.sh profile names: Admin-Alpha1 (not Admin-Alpha001), Alpha002-Admin (not Admin-Alpha002). These are inconsistent — verify before running.