gamma-multi-env-setup

Gamma Multi-Environment Setup

Output

Record environment identity references, approved destinations, policy version, validation result, owner, and rollback path. Do not include credentials or content.

Examples

Use a fictional staging deck to prove the development credential cannot publish to production, rotate the staging credential, and retain only redacted control evidence.

Overview

Configure Gamma API access across development, staging, and production environments. Since Gamma is a SaaS API with no self-hosted option, environment separation is achieved through separate workspaces (API keys), mock servers for development, and environment-aware client configuration.

Prerequisites

• Separate Gamma workspaces (or at minimum separate API keys) per environment
• Secret management solution
• Completed gamma-install-auth setup

Environment Architecture

┌─────────────────────────────────────────────────────────┐
│  Development                                             │
│  API: localhost:9876 (mock server) or Gamma API          │
│  Key: GAMMA_API_KEY=gma_dev_xxx                         │
│  Mock: enabled (no credits consumed)                     │
├─────────────────────────────────────────────────────────┤
│  Staging                                                 │
│  API: public-api.gamma.app (separate workspace)         │
│  Key: GAMMA_API_KEY=gma_stg_xxx                         │
│  Mock: disabled                                          │
├─────────────────────────────────────────────────────────┤
│  Production                                              │
│  API: public-api.gamma.app (production workspace)       │
│  Key: GAMMA_API_KEY=gma_prod_xxx (from secret manager)  │
│  Mock: disabled                                          │
└─────────────────────────────────────────────────────────┘

Instructions

Step 1: Environment Configuration

// src/config/gamma.ts
interface GammaEnvConfig {
  apiKey: string;
  baseUrl: string;
  useMock: boolean;
  timeoutMs: number;
  maxRetries: number;
}

function getGammaConfig(): GammaEnvConfig {
  const env = process.env.NODE_ENV ?? "development";

  const configs: Record<string, Partial<GammaEnvConfig>> = {
    development: {
      baseUrl: process.env.GAMMA_MOCK === "true"
        ? "http://localhost:9876/v1.0"
        : "https://public-api.gamma.app/v1.0",
      useMock: process.env.GAMMA_MOCK === "true",
      timeoutMs: 60000,
      maxRetries: 1,
    },
    staging: {
      baseUrl: "https://public-api.gamma.app/v1.0",
      useMock: false,
      timeoutMs: 30000,
      maxRetries: 3,
    },
    production: {
      baseUrl: "https://public-api.gamma.app/v1.0",
      useMock: false,
      timeoutMs: 30000,
      maxRetries: 5,
    },
  };

  const apiKey = process.env.GAMMA_API_KEY;
  if (!apiKey && !configs[env]?.useMock) {
    throw new Error(`GAMMA_API_KEY required for ${env} environment`);
  }

  return {
    apiKey: apiKey ?? "mock-key",
    ...configs[env],
  } as GammaEnvConfig;
}

export const gammaConfig = getGammaConfig();

Step 2: Environment-Aware Client Factory

// src/gamma/factory.ts
import { createGammaClient } from "./client";
import { gammaConfig } from "../config/gamma";

let client: ReturnType<typeof createGammaClient> | null = null;

export function getGammaClient() {
  if (!client) {
    client = createGammaClient({
      apiKey: gammaConfig.apiKey,
      baseUrl: gammaConfig.baseUrl,
      timeoutMs: gammaConfig.timeoutMs,
    });
  }
  return client;
}

// Reset for testing
export function resetGammaClient() {
  client = null;
}

Step 3: Environment Files

# .env.development
GAMMA_API_KEY=gma_dev_xxxxxxxxxxxx
GAMMA_MOCK=false
NODE_ENV=development
LOG_LEVEL=debug

# .env.test
GAMMA_MOCK=true
NODE_ENV=test
LOG_LEVEL=warn

# .env.staging
GAMMA_API_KEY=gma_stg_xxxxxxxxxxxx
NODE_ENV=staging
LOG_LEVEL=info

# .env.production (use secret manager instead)
# GAMMA_API_KEY loaded from AWS Secrets Manager / Vault
NODE_ENV=production
LOG_LEVEL=warn

Step 4: Production Secret Management

// src/config/secrets.ts
// For production, fetch API key from secret manager at startup

import { SecretsManager } from "@aws-sdk/client-secrets-manager";

let cachedKey: string | null = null;
let cacheExpiry = 0;

async function getProductionApiKey(): Promise<string> {
  if (cachedKey && Date.now() < cacheExpiry) return cachedKey;

  const sm = new SecretsManager({ region: "us-east-1" });
  const secret = await sm.getSecretValue({ SecretId: "gamma/api-key" });
  cachedKey = JSON.parse(secret.SecretString!).apiKey;
  cacheExpiry = Date.now() + 300000; // Cache for 5 minutes

  return cachedKey!;
}

Step 5: Environment Guards

// src/guards.ts
function blockProduction(operation: string) {
  if (process.env.NODE_ENV === "production") {
    throw new Error(`${operation} is blocked in production`);
  }
}

// Block destructive operations in production
async function deleteAllGenerations() {
  blockProduction("deleteAllGenerations");
  // ... cleanup logic for dev/staging
}

// Warn about credit-consuming operations in non-production
function warnCredits(env: string) {
  if (env !== "production" && !gammaConfig.useMock) {
    console.warn("WARNING: Using live Gamma API — credits will be consumed");
  }
}

Step 6: CI/CD Environment Configuration

# .github/workflows/gamma.yml
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      GAMMA_MOCK: 'true'
      NODE_ENV: test
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
      # Uses mock server — no API key needed, no credits consumed

  staging:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/develop'
    env:
      GAMMA_API_KEY: ${{ secrets.GAMMA_STAGING_API_KEY }}
      NODE_ENV: staging
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run test:integration

  production:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    env:
      GAMMA_API_KEY: ${{ secrets.GAMMA_PRODUCTION_API_KEY }}
      NODE_ENV: production
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run deploy

Environment Checklist

Error Handling

Resources

• 12-Factor App Config
• Gamma API Key Management
• AWS Secrets Manager

Next Steps

Proceed to gamma-observability for monitoring setup.