Learn Backstage - Advanced Configuration & Secrets

#Introduction

In episode 8, you enabled auth providers and filled in clientId and clientSecret in app-config.yaml. Episode 9 covers the layer governing all of that: configuration. As Backstage grows, the config file becomes the place where mistakes creep in most often — mistyped values, secrets leaking into the repository, or an environment using settings different from what was intended. This time we tidy it up: how app-config is validated, structured in layers, substituted from the environment, and how secrets are protected through environment variables and Vault.

#App-Config Structure

#The Configuration File Hierarchy

Backstage reads configuration from more than one file. The app-config.yaml file is the same base for all environments, and additional files are merged on top of it — values appearing later override earlier ones. This split keeps one base configuration with per-environment adjustments.

This pattern explains why app-config.local.yaml never enters git: that's where developers keep their local values. Production uses app-config.production.yaml, merged on top of the base file when the application runs.

#Schema Validation with @backstage/config-lint

#Catching Errors Early

Backstage provides the @backstage/config-lint package to validate configuration. This validation checks the config structure against a defined schema, so typos, unknown fields, or wrong data types are caught before the application runs. The rules are simple: the config schema is defined in the app-config.schema.json file, and every field used in app-config.yaml must match it.

yarn backstage-cli config:lint

config:lint reads app-config.yaml along with the override files, compares them against app-config.schema.json, and reports mismatches. You can add it to your CI pipeline so any pull request that breaks the configuration is rejected early.

{
  "backend": {
    "baseUrl": {
      "type": "string",
      "description": "URL dasar dari instance Backstage"
    }
  },
  "custom": {
    "featureFlag": {
      "type": "boolean",
      "default": false
    }
  }
}

The schema above states that backend.baseUrl must be a string and custom.featureFlag a boolean. Fields outside the schema will be flagged as unknown — a signal that something is misspelled or not yet declared.

#Nested Config and Env Substitution

#Nested Config

Backstage configuration is arranged in nested layers. Blocks like backend, auth, catalog, and techdocs each contain sub-blocks, and plugins access values through dot paths like backend.baseUrl. Keeping the config nested makes the file easier to read and avoids name collisions between plugins.

#Env Substitution

Config values can be pulled from environment variables using substitution syntax inside the config file. The syntax only applies within string values, and when the config loads, the variable's value replaces it. This is the main way to supply different values per environment without editing files.

backend:
  baseUrl: ${BACKSTAGE_BASE_URL}
  listen:
    port: 7007
auth:
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

When run, the BACKSTAGE_BASE_URL placeholder is replaced with the value of the BACKSTAGE_BASE_URL environment variable. If the variable isn't available, the process warns — this mechanism makes the config safe to commit because it never contains the secret values themselves.

#Dynamic Config

#Configuration That Can Change at Runtime

Backstage also supports dynamic config — an experimental mechanism for changing parts of the configuration while the application is running, without rebuilding. Some plugins can read dynamic configuration loaded from a special file and updated through an API, so small adjustments don't have to wait for a deploy cycle.

The usage pattern: values that change often (for example feature flags or long lists) live in dynamic config, while stable values stay in app-config.yaml. Use dynamic config with care — putting secrets there actually reduces the value of the environment control you've already built.

#Secrets Management

#Environment-Variable Based

The most basic — and most important — way to store Backstage secrets is the environment variable. clientId, clientSecret, Vault tokens, and cloud provider access keys are all supplied through the environment, not written in config files. These values are usually defined on the deployment platform, in a gitignored local .env file, or in a Kubernetes secret manager.

export AUTH_GITHUB_CLIENT_ID=Ov23li-example
export AUTH_GITHUB_CLIENT_SECRET=secretexample
export VAULT_TOKEN=hv-token-example
yarn dev

Once the environment variables are available, app-config.yaml just references them through environment substitution like AUTH_GITHUB_CLIENT_ID. Credentials are never written in a file that enters git, and each environment uses its own values.

#Vault Integration

When the number of secrets grows, environment variables alone start getting hard to manage. Vault offers a centralized home: secrets are stored in Vault, and Backstage pulls them through the Vault backend plugin. The backend plugin loads secrets from specific paths and makes them available to other plugins like the scaffolder or catalog, based on the configured address and token.

vault:
  baseUrl: ${VAULT_BASE_URL}
  token: ${VAULT_TOKEN}
  kvVersion: 2

Secrets still flow through environment variables (the Vault token), but the secret contents themselves are stored and managed in Vault — including rotation, audit logs, and access control. This is a big step from writing credentials in files toward centralized, auditable storage.

#Conclusion

In this episode 9, you tidied up the configuration foundation: the app-config.yaml hierarchy with local and production override files, schema validation with @backstage/config-lint, nested config with dot paths, environment variable substitution, dynamic config for values that change at runtime, and environment-based secrets management plus Vault integration without ever putting credentials in code.

The key takeaways:

• Configuration is layered — the base file is merged with per-environment files; local files never enter git.
• Validate before running — config:lint catches typos and wrong types in CI, not in production.
• Secrets live in the environment — substitution fills them in at runtime, and app-config.yaml stays safe to commit.
• Vault for scale — once the number of secrets grows, move them to Vault so they can be rotated and audited.

In the next episode, episode 10, we return to the Scaffolder at a higher level: Advanced Scaffolder & Custom Actions — branching workflows with conditional logic, output as links and entities, permissions for templates, and custom actions that provision cloud resources from internal tooling.