From 97beeecb61c4c39a5b3e51a06a9e6dc4fcf8950c Mon Sep 17 00:00:00 2001
From: JP Dhabolt <jdhabolt@agero.com>
Date: Tue, 30 Mar 2021 17:50:14 +0000
Subject: [PATCH] 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 | 11 ++++++++---
 docs/conf/writing.md          | 28 ++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/.changeset/fair-geese-yell.md b/.changeset/fair-geese-yell.md
index d4d27c4885..5ca86b8913 100644
--- a/.changeset/fair-geese-yell.md
+++ b/.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.
diff --git a/docs/conf/writing.md b/docs/conf/writing.md
index 057675c98e..ac8509db0a 100644
--- a/docs/conf/writing.md
+++ b/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-----
+```