Support multi-environment GitHub Actions generation with environment.json

[barronlroth]

Summary

cxas init-github-action currently generates workflows for one target CXAS app. Many production teams use separate dev, staging, and prod CXAS apps, often in separate GCP projects, and rely on CX Agent Studio environment.json files to promote the same exported app between environments.

It would be useful for SCRAPI to support a first-class multi-environment GitHub Actions generation workflow.

Background

CX Agent Studio exports include an environment.json file for environment-specific settings such as Cloud Storage buckets, service endpoints, data store URIs, secret versions, service accounts, and related external dependencies. During import, CX Agent Studio applies values from environment.json to $env_var placeholders in the exported app resources.

Reference: https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/export#environment_file

SCRAPI already exposes the right primitive for this at deploy time:

cxas push \
  --to projects/PROJECT_ID/locations/LOCATION/apps/APP_ID \
  --env-file path/to/environment.json

However, the generated GitHub Actions templates are currently oriented around a single app target and a single auth configuration.

Desired workflow

A team should be able to manage one source-controlled app export and promote it across multiple target apps/projects, for example:

agent-project/
  cxas_app/App_Name/
    app.json
    agents/
    tools/
  environments/
    dev.environment.json
    staging.environment.json
    prod.environment.json

Promotion model:

pull request -> validate temporary/dev app
merge to main -> deploy dev
approval -> deploy staging
approval or release -> deploy prod

Each environment may have its own:

• CXAS app resource name
• GCP project
• location
• Workload Identity Provider
• service account
• environment.json file
• GitHub Environment approvals or branch/tag trigger policy

Possible CLI designs

Option A: repeated flags

cxas init-github-action \
  --app-dir agent-project/cxas_app/App_Name \
  --environment dev:projects/DEV_PROJECT/locations/us/apps/DEV_APP_ID:environments/dev.environment.json \
  --environment staging:projects/STAGING_PROJECT/locations/us/apps/STAGING_APP_ID:environments/staging.environment.json \
  --environment prod:projects/PROD_PROJECT/locations/us/apps/PROD_APP_ID:environments/prod.environment.json

Option B: config file

cxas init-github-action --environments-file cxas-environments.yaml

Example:

environments:
  dev:
    app_name: projects/DEV_PROJECT/locations/us/apps/DEV_APP_ID
    env_file: environments/dev.environment.json
    workload_identity_provider: projects/DEV_NUMBER/locations/global/workloadIdentityPools/github/providers/dev
    service_account: github-cxas-dev@DEV_PROJECT.iam.gserviceaccount.com
    trigger: main
  staging:
    app_name: projects/STAGING_PROJECT/locations/us/apps/STAGING_APP_ID
    env_file: environments/staging.environment.json
    workload_identity_provider: projects/STAGING_NUMBER/locations/global/workloadIdentityPools/github/providers/staging
    service_account: github-cxas-staging@STAGING_PROJECT.iam.gserviceaccount.com
    requires_approval: true
  prod:
    app_name: projects/PROD_PROJECT/locations/us/apps/PROD_APP_ID
    env_file: environments/prod.environment.json
    workload_identity_provider: projects/PROD_NUMBER/locations/global/workloadIdentityPools/github/providers/prod
    service_account: github-cxas-prod@PROD_PROJECT.iam.gserviceaccount.com
    requires_approval: true

Expected generated behavior

The generator could produce either:

• one workflow per environment, such as deploy_dev.yml, deploy_staging.yml, and deploy_prod.yml; or
• one deploy workflow with a matrix / GitHub Environments setup.

Generated deploy steps should pass the environment-specific file to SCRAPI:

cxas push \
  --app-dir agent-project/cxas_app/App_Name \
  --to projects/ENV_PROJECT/locations/LOCATION/apps/ENV_APP_ID \
  --env-file environments/ENV.environment.json

Why this matters

Without a supported generator path, customers need to hand-edit generated GitHub Actions to add multi-environment promotion. That makes the generated workflow harder to regenerate safely when SCRAPI templates improve, and it increases the risk of deploying the right app code with the wrong environment-specific dependencies.

A first-class multi-environment option would make the SCRAPI CI/CD story clearer for production teams using dev/staging/prod isolation across GCP projects.