Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/glean-multi-env-setup/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill glean-multi-env-setup. Copyright stays with the author (MIT).

Glean Multi-Environment Setup

Overview

Glean enterprise search requires environment isolation to prevent test data from polluting production search results. Each environment uses its own datasource names, API tokens, and connector configurations. Sandbox indexes synthetic test documents, staging indexes a curated subset of real documents for search quality validation, and production indexes the full corpus. Connector changes must be tested in staging before promotion to avoid breaking search relevance for end users.

Environment Configuration

const gleanConfig = (env: string) => ({
  development: {
    apiToken: process.env.GLEAN_API_TOKEN_DEV!, baseUrl: "https://sandbox.glean.com/api/v1",
    datasourceSuffix: "_sandbox", indexingEnabled: true, searchQualityChecks: false,
  },
  staging: {
    apiToken: process.env.GLEAN_API_TOKEN_STG!, baseUrl: "https://staging.glean.com/api/v1",
    datasourceSuffix: "_staging", indexingEnabled: true, searchQualityChecks: true,
  },
  production: {
    apiToken: process.env.GLEAN_API_TOKEN_PROD!, baseUrl: "https://app.glean.com/api/v1",
    datasourceSuffix: "_prod", indexingEnabled: true, searchQualityChecks: false,
  },
}[env]);

Environment Files

# Per-env files: .env.development, .env.staging, .env.production
GLEAN_API_TOKEN_{DEV|STG|PROD}=<token>
GLEAN_BASE_URL=https://{sandbox|staging|app}.glean.com/api/v1
GLEAN_DATASOURCE_SUFFIX={_sandbox|_staging|_prod}
GLEAN_INSTANCE={sandbox|staging|production}

Environment Validation

function validateGleanEnv(env: string): void {
  const suffix = { development: "_DEV", staging: "_STG", production: "_PROD" }[env];
  const required = [`GLEAN_API_TOKEN${suffix}`, "GLEAN_BASE_URL", "GLEAN_INSTANCE"];
  const missing = required.filter((k) => !process.env[k]);
  if (missing.length) throw new Error(`Missing Glean env vars for ${env}: ${missing.join(", ")}`);
}

Promotion Workflow

# 1. Index test documents in sandbox
curl -X POST "$GLEAN_BASE_URL/indexing/datasources/wiki_sandbox/documents" \
  -H "Authorization: Bearer $GLEAN_API_TOKEN_DEV" -d @test-docs.json

# 2. Validate search quality in staging
curl "$GLEAN_BASE_URL/search" -H "Authorization: Bearer $GLEAN_API_TOKEN_STG" \
  -d '{"query": "onboarding guide"}' | jq '.results[:3].title'

# 3. Compare relevance scores against baseline
node scripts/compare-search-quality.js --env staging --baseline baseline.json

# 4. Promote connector config to production
cp connectors/staging/*.json connectors/production/
curl -X POST "$GLEAN_BASE_URL/indexing/datasources/wiki_prod/crawl" \
  -H "Authorization: Bearer $GLEAN_API_TOKEN_PROD"

Environment Matrix

Error Handling

Prerequisites

• Distinct credentials, opaque datasource names, and network destinations for sandbox, staging, and production.
• A secret-manager reference per environment, protected promotion approval, and a documented production rollback revision.
• Synthetic fixtures for sandbox and an owner-approved minimized staging sample; never copy production credentials or unrestricted documents into CI.

Instructions

1. Validate the selected environment against an explicit allowlist before reading credentials or creating a datasource.
2. Apply versioned, idempotent configuration changes in sandbox and run synthetic allow/deny probes.
3. Promote to staging only with owner approval, bounded samples, redacted observability, and comparison against the prior relevance/freshness baseline.
4. Canary one production datasource after protected review; halt and restore the prior revision for an ACL, freshness, or error-budget regression.
5. Record only environment, opaque source IDs, revisions, aggregate counts, and rollback results in the promotion receipt.

Output

Produce a promotion receipt with environment, configuration revision, datasource, synthetic test counts, staging/canary result, owner approval, and rollback reference. Exclude credentials, documents, queries, and real identities.

Examples

env=staging; datasource=sandbox-guides-stg; config=r22; allow=pass; deny=pass; relevance_delta=within-budget; rollback=r21 is sufficient evidence for a controlled promotion.

Resources

• Glean Developer Portal
• Indexing API
• Search API

Next Steps

See glean-deploy-integration.