Runbook

Publishing Issues

400 on Publish

Symptoms: Publish request rejected

Cause: Invalid slug, version, file path, or bundle size

Resolution:

# Run with dry-run to see validation errors
scrm extension publish --tenant acme-corp --dry-run

Common issues:

• Slug contains special characters (use a-z0-9- only)
• Version not semver (use 1.0.0 format)
• Bundle exceeds size limit

409 on Publish

Symptoms: Version already exists error

Cause: Extension versions are immutable

Resolution:

# Publish new version
scrm extension publish --tenant acme-corp --version 1.0.1

Checksum Mismatch

Symptoms: Upload fails with checksum error

Cause: Bundle contents changed after checksum computed

Resolution:

# Rebuild and re-publish
pnpm build
scrm extension publish --tenant acme-corp

Asset Issues

404 on Assets

Symptoms: Extension loads but assets fail to load

Diagnosis:

1. Check GCS object exists
2. Verify installation is active
3. Confirm path matches

Resolution:

# List objects in GCS bucket
gsutil ls gs://{bucket}/org_123/dashboard/1.0.0/

403 on Assets

Symptoms: Permission denied on assets

Cause: GCS permissions or service account issue

Resolution:

• Verify service account has bucket access
• Check bucket policy

Token Issues

Token Request Fails

Symptoms: Extension cannot get token

Cause:

• EXTENSION_TOKEN_SECRET mismatch
• No active installation

Diagnosis:

# Check server logs
grep "ExtensionToken" server.log

Resolution:

• Verify EXTENSION_TOKEN_SECRET matches between services
• Confirm extension is installed and active

Signature Invalid

Symptoms: "Signature Invalid" error

Cause: Secret mismatch

Resolution:

# Verify secrets match
echo $EXTENSION_TOKEN_SECRET  # Should match in all services

Production Issues

Works Locally, Not Production

Symptoms: Extension works in dev but not prod

Cause: GCS credentials misconfigured

Resolution:

# Verify environment
echo $EXTENSION_GCS_BUCKET
echo $EXTENSION_GCS_PROJECT_ID
echo $EXTENSION_GCS_KEY_FILE

Debug Commands

# List extensions for org
GET /api/extensions?org=acme-corp

# Check installation status
GET /api/extensions/{slug}/installation?org=acme-corp

# View audit logs
GET /api/audit-logs?type=EXTENSION_PUBLISH