Document transitional deploy env handling

Author: anth-volk

.env.example

@@ -1,6 +1,7 @@
-# For local development only, uncomment this if you need to point ADC at a
-# specific credential file. The deployed App Engine service uses its attached
-# service account instead.
+# Left commented on purpose so `make setup-env` does not poison ADC with a fake
+# path in CI, Docker builds, or local shells. Uncomment only if your local
+# machine needs to point ADC at a real credential file. The deployed App Engine
+# service uses its attached service account instead.
 # GOOGLE_APPLICATION_CREDENTIALS=/path/to/policyengine_gcp_credentials.json
 
 # Password for connecting to the PolicyEngine database

.github/workflows/push.yml

@@ -156,6 +156,9 @@ jobs:
       - name: Validate App Engine deployment configuration
         run: bash .github/scripts/validate_app_engine_deploy_env.sh
         env:
+          # Transitional: these values are still passed into the deploy bundle
+          # by gcp/export.py. Long-term target is a generic image plus runtime
+          # config / Secret Manager lookups instead of image bake-in.
           SIMULATION_API_URL: ${{ secrets.SIMULATION_API_URL }}
           GATEWAY_AUTH_ISSUER: ${{ secrets.GATEWAY_AUTH_ISSUER }}
           GATEWAY_AUTH_AUDIENCE: ${{ secrets.GATEWAY_AUTH_AUDIENCE }}
@@ -164,6 +167,9 @@ jobs:
       - name: Build staging deploy image
         run: bash .github/scripts/build_app_engine_image.sh
         env:
+          # Transitional: these values are still rendered into the App Engine
+          # image today. Long-term target is to stop passing them into the
+          # image build and supply them as runtime config / Secret Manager data.
           APP_ENGINE_IMAGE_TAG: policyengine-api:staging-${{ steps.version.outputs.version }}
           POLICYENGINE_DB_PASSWORD: ${{ secrets.POLICYENGINE_DB_PASSWORD }}
           POLICYENGINE_GITHUB_MICRODATA_AUTH_TOKEN: ${{ secrets.POLICYENGINE_GITHUB_MICRODATA_AUTH_TOKEN }}
@@ -178,6 +184,9 @@ jobs:
       - name: Deploy staging version
         run: bash .github/scripts/deploy_app_engine_version.sh
         env:
+          # Transitional: deploy_app_engine_version.sh still prepares a bundle
+          # from these values before App Engine deploy. Long-term target is one
+          # generic image plus runtime config / Secret Manager.
           APP_ENGINE_VERSION: ${{ steps.version.outputs.version }}
           APP_ENGINE_PROMOTE: "0"
           POLICYENGINE_DB_PASSWORD: ${{ secrets.POLICYENGINE_DB_PASSWORD }}
@@ -280,6 +289,9 @@ jobs:
       - name: Validate App Engine deployment configuration
         run: bash .github/scripts/validate_app_engine_deploy_env.sh
         env:
+          # Transitional: these values are still passed into the deploy bundle
+          # by gcp/export.py. Long-term target is a generic image plus runtime
+          # config / Secret Manager lookups instead of image bake-in.
           SIMULATION_API_URL: ${{ secrets.SIMULATION_API_URL }}
           GATEWAY_AUTH_ISSUER: ${{ secrets.GATEWAY_AUTH_ISSUER }}
           GATEWAY_AUTH_AUDIENCE: ${{ secrets.GATEWAY_AUTH_AUDIENCE }}
@@ -288,6 +300,9 @@ jobs:
       - name: Deploy production version
         run: bash .github/scripts/deploy_app_engine_version.sh
         env:
+          # Transitional: deploy_app_engine_version.sh still prepares a bundle
+          # from these values before App Engine deploy. Long-term target is one
+          # generic image plus runtime config / Secret Manager.
           APP_ENGINE_VERSION: ${{ steps.version.outputs.version }}
           APP_ENGINE_PROMOTE: "0"
           POLICYENGINE_DB_PASSWORD: ${{ secrets.POLICYENGINE_DB_PASSWORD }}

README.md

@@ -35,6 +35,33 @@ make install
 make setup-env
 ```
 
+### 3a. Configure environment variables
+
+`make setup-env` creates a local `.env` from `.env.example`. At minimum, local development expects values for:
+
+- `POLICYENGINE_DB_PASSWORD`
+- `POLICYENGINE_GITHUB_MICRODATA_AUTH_TOKEN`
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `HUGGING_FACE_TOKEN`
+
+If you need a local Google credential file for ADC, uncomment and set:
+
+- `GOOGLE_APPLICATION_CREDENTIALS`
+
+Keep that commented unless you are pointing at a real local credential file. The deployed App Engine service uses its attached service account instead.
+
+If you are running against an auth-protected simulation gateway outside the managed deploy path, you may also need:
+
+- `SIMULATION_API_URL`
+- `GATEWAY_AUTH_REQUIRED`
+- `GATEWAY_AUTH_ISSUER`
+- `GATEWAY_AUTH_AUDIENCE`
+- `GATEWAY_AUTH_CLIENT_ID`
+- one of `GATEWAY_AUTH_CLIENT_SECRET` or `GATEWAY_AUTH_CLIENT_SECRET_RESOURCE`
+
+Managed App Engine deploys currently still render some runtime config into the image bundle. Long-term, we intend to stop doing that and supply environment-specific config at runtime instead.
+
 ### 4. Start a server on localhost to see your changes
 
 Run: