Skip to content

Cloud Environment Strategy (Xcode + Cognito Placeholders)

Last updated: 2026-04-06

This document defines the app-side environment strategy for cloud auth and API routing.

Goals

  • Keep one codebase for development and customer cutovers.
  • Avoid committing secrets.
  • Make environment selection explicit and reproducible in Xcode.
  • Support local developer overrides without changing committed files.

Configuration Layers

  1. Info.plist build-setting substitutions (non-secret defaults).
  2. xcconfig files for baseline values.
  3. Xcode scheme environment variables for per-scheme overrides.

Runtime precedence is:

  1. Process environment variables (scheme/env injection).
  2. Info.plist values.

Files

  • Build config defaults:
  • Config/Build/Base.xcconfig
  • Config/Build/Debug.xcconfig
  • Config/Build/Release.xcconfig
  • Environment defaults:
  • Config/Environments/CC-DEV.xcconfig
  • Shared dev scheme:
  • BionicLoop.xcodeproj/xcshareddata/xcschemes/CC-DEV.xcscheme

Debug.xcconfig currently includes CC-DEV.xcconfig as the default dev baseline. Release.xcconfig also currently includes CC-DEV.xcconfig so TestFlight archives resolve a real Cognito/API configuration instead of placeholder values.

Temporary policy note:

  • this Release -> CC-DEV mapping is a placeholder only,
  • it exists so current TestFlight builds can exercise the authenticated workflow,
  • it should be replaced with a dedicated staging and/or production environment mapping as soon as those AWS environments are available.

Note: URL values in .xcconfig files use :/$()/ to avoid // being parsed as a comment.

Info.plist Keys

These keys are substituted at build time and read at runtime:

  • BLAuthEnvironmentName
  • BLAPIBaseURL
  • BLCognitoUserPoolID
  • BLCognitoUserPoolClientID
  • BLCognitoHostedUIDomain
  • BLCognitoSignInRedirectURI
  • BLCognitoSignOutRedirectURI

Runtime Loader

AuthEnvironment (in BionicLoop/App/ContentView.swift) resolves:

  • environment variable override keys:
  • BL_AUTH_ENV_NAME
  • BL_API_BASE_URL
  • BL_COGNITO_USER_POOL_ID
  • BL_COGNITO_USER_POOL_CLIENT_ID
  • BL_COGNITO_HOSTED_UI_DOMAIN
  • BL_COGNITO_SIGN_IN_REDIRECT_URI
  • BL_COGNITO_SIGN_OUT_REDIRECT_URI
  • fallback to the corresponding Info.plist keys.

The loader exposes isConfigured so placeholder values are easy to detect.

Creating a Customer Environment

  1. Add Config/Environments/<CUSTOMER>.xcconfig with non-secret defaults.
  2. Decide default policy:
  3. include that file in Config/Build/Debug.xcconfig, or
  4. keep Debug.xcconfig generic and set scheme env overrides only.
  5. Decide Release/TestFlight policy separately:
  6. either map Config/Build/Release.xcconfig to the intended environment, or
  7. create a dedicated release-style config such as Release-<CUSTOMER>.xcconfig for archive/TestFlight use.
  8. Duplicate CC-DEV.xcscheme to <CUSTOMER>-DEV.xcscheme.
  9. Set <CUSTOMER>-DEV scheme environment variables to the new AWS values for local runs as needed.
  10. Validate:
  11. app launch logs [AuthEnvironment] ...
  12. auth flow uses expected domain/user-pool config.

Important:

  • scheme environment variables help local Xcode runs,
  • archived/TestFlight apps depend on the values resolved into Info.plist by build settings,
  • do not rely on scheme-only overrides for TestFlight.

Secret Handling

  • Do not store client secrets in app config.
  • Keep credentials/tokens in CI secret stores or AWS secret systems.
  • Keep committed config values non-secret and auditable.