Update docs and changeset

Signed-off-by: JP Dhabolt john.p.dhabolt@gmail.com
Signed-off-by: JP Dhabolt <jdhabolt@agero.com>

.changeset/fair-geese-yell.md

@@ -2,8 +2,13 @@
 '@backstage/config-loader': minor
 ---
 
-Add support for environment variable substitution in `$include` transform values.
+Add support for environment variable substitution in `$include`, `$file` and
+`$env` transform values.
 
-This change allows for including dynamic paths, such as environment specific secrets by using the same environment variable substitution already supported outside of the `$include` transform (`${..}`).
+This change allows for including dynamic paths, such as environment specific
+secrets by using the same environment variable substitution (`${..}`) already
+supported outside of the various include transforms.
 
-If you are currently using the syntax `${...}` in your `$include` values, you will need to escape the substitution by using `$${...}` instead.
+If you are currently using the syntax `${...}` in your include transform values,
+you will need to escape the substitution by using `$${...}` instead to maintain
+the same behavior.

docs/conf/writing.md

@@ -177,3 +177,31 @@ configuration value will evaluate to `undefined`.
 
 The substitution syntax can be escaped using `$${...}`, which will be resolved
 as `${...}`.
+
+## Combining Includes and Environment Variable Substitution
+
+The Includes and Environment Variable Substitutions can be combined to do
+something like read a secrets configuration for a specific environment. For
+example:
+
+```yaml
+integrations:
+  github:
+    - host: github.com
+      apps:
+        - $include: secrets.${BACKSTAGE_ENVIRONMENT}.yaml
+```
+
+Example `secrets.prod.yaml`:
+
+```yaml
+appId: 1
+webhookUrl: https://smee.io/foo
+clientId: someGithubAppClientId
+clientSecret: someGithubAppClientSecret
+webhookSecret: someWebhookSecret
+privateKey: |
+  -----BEGIN RSA PRIVATE KEY-----
+  SomeRsaPrivateKey
+  -----END RSA PRIVATE KEY-----
+```