Overview

Context

• Front End Code Repository
• Infrastructure Definition
• Example of back-end deployment
• Configuration Information for Infrastructure and Partitions for each environment

The current deployment pipeline for the Arda frontend is based on AWS Amplify connecting to specific branches of the arda-frontend-app repository. Specifically:

• dev branch:
  • URL: dev.alpha002.app.arda.cards
  • AWS Account: 139852620346
  • AWS Region: us-east-1
  • Infrastructure: Alpha002
  • Partition: dev
  • Amplify App Id: d38w5m1ngjza76
• stage branch:
  • URL: stage.alpha002.app.arda.cards
  • AWS Account: 139852620346
  • AWS Region: us-east-1
  • Infrastructure: Alpha002
  • Partition: stage
  • Amplify App Id: d1kbrvra79y8sc
• main branch:
  • URL: prod.alpha001.app.arda.cards
  • Published URL: live.app.arda.cards
  • AWS Account: 009765408297
  • AWS Region: us-east-2
  • Infrastructure: Alpha001
  • Partition: prod
  • Amplify App Id: duhexavnwh88g

The GitHub promotion relies on a sequence from dev to stage to main, each step with a review and approval process and extensive automated tests, which makes it very time consuming and slows down the release process.

Goal

Transition the Arda frontend deployment pipeline to use GitHub Actions instead of the current Amplify based sync of individual branches. The process should be similar to how the back-end is deployed, using GitHub actions to build, test and deploy from the main branch to the correct partition/Amplify Application.

Additional Constraints:

• The changes should be additive and separate to the current pipeline until it is fully tested and validated.
• The new pipeline should be initialy triggered by hand instead of on push or PR.
• The new pipeline should work strictly from the main branch once all PR checks have passed.

Additional Decisions

No new properties in purpose-configuration

The initial design proposed adding frontend_aws_role, amplify_app_id, and amplify_application_branch_name to each partition’s .properties file. This was replaced with a derivation-based approach that requires no changes to the purpose-configuration repository:

1. Frontend IAM role: Derived from the existing aws_role property by appending FrontEnd to the role name (e.g., Alpha001-API-GitHubAction becomes Alpha001-API-GitHubActionFrontEnd). This follows the same pattern used by the backend, where the infrastructure identity is embedded in the role ARN.
2. Amplify App ID: Read from the CloudFormation export ${Infrastructure}-${Partition}-I-AmplifyAppId. For the demo app (created via CloudFormation), this export is created automatically by amplify.cfn.yaml. For existing manually-created apps (dev, stage, prod), a lightweight CloudFormation stack (amplifyExports.cfn.yaml) publishes the export with the known app ID.
3. Amplify Branch Name: Read from the CloudFormation export ${Infrastructure}-${Partition}-I-AmplifyBranchName. Same mechanism as above — created by amplifyBranch.cfn.yaml for new apps, by the lightweight export stack for existing apps.
4. Infrastructure prefix: Parsed from the aws_role role name (text before -API-GitHubAction) to construct CloudFormation export names.

This eliminates the need for purpose-configuration versioning (v2 tag) and removes the purpose-configuration repository from the project’s change set entirely.

Uniform branch name mapping in amm.sh

The Amplify branch resource names are a legacy of the original branch-sync model. The prod app’s branch resource is named main (not prod) because it was originally connected to the main git branch. Rather than special-casing prod, amm.sh defines a partition-to-branch-name mapping for all partitions — including the trivial matches (dev→dev, stage→stage). This makes the design uniform and avoids reliance on a naming convention that doesn’t hold for all cases:

Partition	Amplify Branch Resource Name
dev	dev
stage	stage
demo	demo
prod	main

The mapping is the single source of truth. It is used when deploying CloudFormation stacks and when creating lightweight export stacks. The GitHub Actions workflow never derives or assumes branch names — it reads them from CloudFormation exports.

Lightweight CloudFormation export stacks for existing apps

The existing dev, stage, and prod Amplify apps were created manually (not via CloudFormation). They have no CloudFormation stacks and therefore no exports. A minimal CloudFormation template (amplifyExports.cfn.yaml) is deployed per partition at cutover to publish the AmplifyAppId and AmplifyBranchName exports with the known values. This gives the workflow a uniform lookup mechanism regardless of how the app was originally created. See Amplify Current Configuration for the live state of all existing apps.

PR preview deployments for developer feedback

The current dev → stage → main promotion model requires a full PR review cycle before a developer can see their changes deployed. This slows down the development feedback loop significantly.

The new pipeline uses Amplify’s built-in pull request preview feature on the dev Amplify app to provide fast developer feedback without bypassing the official deployment pipeline.

Intended workflow:

1. A developer makes a change and opens a PR against main.
2. Amplify automatically builds the PR branch and deploys it to a temporary preview URL (e.g., pr-42.d38w5m1ngjza76.amplifyapp.com). Amplify posts the preview URL as a comment on the GitHub PR.
3. The developer verifies the application at the preview URL and shares it with their team for review. The preview uses the same backend as the dev partition (same API Gateway, Cognito pools, database) since it inherits the dev app’s environment variables.
4. Each subsequent push to the PR branch automatically redeploys to the same preview URL — no new PR needed.
5. Once the PR is reviewed and merged to main, the official deployment pipeline triggers: CI runs, then deploy.yaml deploys sequentially to dev → stage → demo → prod with authorization gates.
6. The preview URL is automatically deleted when the PR is closed or merged.

Implementation: Enable enablePullRequestPreview: true on the dev Amplify app’s branch resource. This is an Amplify-managed feature — no GitHub Actions workflow changes are needed. PR previews build independently of GitHub Actions CI; they trigger immediately on PR open/push via a GitHub webhook.

Quality gate: The Amplify build spec includes npm run test (Jest unit tests) before npm run build. If unit tests fail, the build fails and the preview is not deployed. This provides a lightweight quality gate without requiring GitHub Actions integration. Lint and e2e tests remain GitHub Actions-only and gate the merge to main, not the preview.

No Cognito callback URL concern: The application uses direct password authentication (USER_PASSWORD_AUTH via InitiateAuthCommand), not an OAuth/OIDC authorization code flow. There are no callback URLs to configure — sign-in works via API calls regardless of the serving domain. PR preview deployments will authenticate against the dev Cognito user pool without any additional configuration.