Backstage App Configuration

Backstage app configuration

Manage Backstage configuration as a layered, schema-validated contract rather than a collection of untracked environment values.

When to invoke

• "Configure app-config.production.yaml."
• "Why is this Backstage config key not loading?"
• "Add an integration without committing its secret."
• "Validate Backstage config before deployment."

Configuration model

• app-config.yaml holds shared defaults.
• Additional app-config.<environment>.yaml files or explicit config arguments provide overrides.
• BACKSTAGE_ENV selects the conventional environment-specific config layer when supported by the target repository.
• Environment variables and approved secret providers supply sensitive values.
• Frontend-visible configuration is bundled into the browser and must never contain secrets.

Procedure

1. Detect repository mode, Backstage version, launch command, and actual config load order.

2. Inventory config files, environment selection, schemas, and ${ENV_VAR} references.

3. Classify each requested value as shared default, environment override, secret, or frontend-visible configuration.

4. Update the smallest config layer and matching schema or documentation.

5. Preserve integration boundaries and avoid duplicating the same key in unrelated layers.

6. Run the repository's current equivalent of:

   yarn backstage-cli config:check
   

7. If startup still fails, inspect the effective config and error without printing secret values.

8. Report the resolved layer, schema result, required environment names, and deployment handoff.

Gotchas

• Later config layers override earlier values; they do not merge every nested shape identically.
• A valid YAML document can still fail Backstage schema validation.
• Config available to the frontend is public to browser users.
• Sign-in credentials and GitHub integration credentials have different purposes.

Output template

## Backstage configuration result

**Environment:** <name>
**Load order:** <files and selectors>

| Key family | Source | Visibility | Validation |
| --- | --- | --- | --- |

### Required external values
- `<ENV_NAME>`: <purpose, not value>

Quality gate

• Config load order and target environment are evidenced.
• Secrets remain external and are not printed.
• Frontend-visible values contain no credentials.
• Changed keys are covered by current schemas.
• config:check or the repository equivalent passes.
• Deployment-specific overrides are documented.