Update README.md

mike-schenk · web-flow · commit ef57338f19a0 · 2023-09-01T16:41:27.000-06:00
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Set Environment Variables by Scope
 
-This action takes specially formatted environment variables and/or an input file to emit scoped environment variables.
+This action sets environment variables, (and optionally step outputs), to different values determined by a provided `scope`. The values for each variable and scope can be provided in specially-named environment variables or an input file.
 
 ## Index <!-- omit in toc -->
 
@@ -23,21 +23,17 @@ This action takes specially formatted environment variables and/or an input file
 
 ## Inputs
 
-| Parameter                 | Is Required | Description                                                                                                                                          |
-| ------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `scope`                   | true        | The scope is used to select key names and values to be set as environment vars, key names that do not contain the scope will not be exported         |
-| `input-file`              | false       | A specially formatted YAML file containing possible environment variable candidates with their associated scopes                                     |
-| `create-output-variables` | false       | Create output variables (in addiction to environment variables) for use in other steps and jobs, accepts true or false, defaults to false            |
-| `error-on-no-match`       | false       | An error will be thrown if no env or output variables are created, a warning will appear for all keys that don't provide a value for the input scope |
-| `custom-error-message`    | false       | The error message that will be displayed if no environment or output variables are created, `error_on_no_match` must be set to true                  |
-
-### Environment Variables
-
-This action relies heavily on environment variables as part of its inputs. _Any_ environment variable with an [`@` in it's key name](#key-name) is used as a possible candidate for scoped output.  More information is included in the [usage instructions](#usage-instructions) section.
+| Parameter                 | Is Required | Description                                                                                                                                                    |
+| ------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scope`                   | true        | The scope is used to identify which value to select for each key name. See the usage instructions below.                                                       |
+| `input-file`              | false       | A specially formatted YAML file containing possible environment variable candidates with their associated scopes.                                              |
+| `create-output-variables` | false       | Create output variables (in addiction to environment variables) for use in other steps and jobs. Accepts true or false. Defaults to false.                     |
+| `error-on-no-match`       | false       | An error will be thrown if no environment variables or outputs are created, a warning will appear for all keys that don't provide a value for the input scope. |
+| `custom-error-message`    | false       | The error message that will be displayed if no environment or output variables are created. `error_on_no_match` must be set to true                            |
 
 ## Outputs
 
-Varies by usage, but is based on [`key-name`](#key-name) specified in environment variables and the `input-file` specified.
+Varies by usage, but is based on the [`key-name`](#key-name)s supplied in environment variables and the `input-file`.
 
 ## Usage Examples
 
@@ -47,9 +43,16 @@ Varies by usage, but is based on [`key-name`](#key-name) specified in environmen
 on:
   workflow_dispatch:
     inputs:
-      environment:
-        description: The environment to deploy to.
+      destination:
+        description: The destination to deploy to.
         required: true
+        options:
+          - dev
+          - qa
+          - stage
+          - stage-secondary
+          - prod
+          - prod-secondary
 
 jobs:
   setup:
@@ -58,7 +61,7 @@ jobs:
       env-scope: ${{ steps.env-scope.output.ENVIRONMENT }}
 
     steps:
-      - name: Set environment scope
+      - name: Set environment
         id: env-scope
         uses: im-open/set-environment-variables-by-scope@v1.1.4
         with:
@@ -67,10 +70,10 @@ jobs:
           error_on_no_match: true
           custom_error_message: 'The environment must be Dev, QA, Stage or Prod'
         env:
-          ENVIRONMENT@dev d development: dev
-          ENVIRONMENT@qa a: qa
-          ENVIRONMENT@stage s stg: stage
-          ENVIRONMENT@prod p production: prod
+          ENVIRONMENT@dev: dev
+          ENVIRONMENT@qa: qa
+          ENVIRONMENT@stage stage-secondary: stage
+          ENVIRONMENT@prod prod-secondary: prod
 
       - run: echo "The current environment is ${{ env.ENVIRONMENT }}."
 
@@ -116,23 +119,23 @@ inFileName2@dev qa stage prod demo: 'file value for all environments'
 
 ### Usage Instructions
 
-The format of the `env` variable and the `input-file` contents are the same and follows this format:
+The format of each input environment variable and each entry in the `input-file` are the same and follows this format:
 
 `[key-name]@[scope-array]: [key-value]`
 
-#### `key-name`
+#### _`key-name`_
 
-The resulting environment variable name. It does accept a wide variety of name convention formats including spaces, dashes, periods, and underscores. While it's been tested and found to be fairly flexible, it is possible to make environment variable names that aren't usable by one or more of the target action runner operating systems.
+The resulting environment variable and output name. It can contain practically any 'printable' characters including spaces, dashes, colons, periods, and underscores. While it's been tested and found to be fairly flexible, it is possible to make environment variable names that aren't usable by one or more of the target action runner operating systems.
 
-**_Key names intended for use as output variables that are referenced in the workflow can only contain letters, numbers, dashes and underscores._** Any other punctuation or space characters cannot be processed and will cause errors when attempting to reference them later in a workflow.
+**_Key names intended for use as output variables can only contain letters, numbers, dashes and underscores._** Any other punctuation or space characters cannot be processed and will cause errors when attempting to reference them later in a workflow.
 
-#### `scope-array`
+#### _`scope-array`_
 
-A space delimited array of scope strings that the environment variable could be valid for.  The filter by which keys/values will be selected is the `scope` action input. The scope value comparison is _not_ case sensitive.
+A space delimited array of scope strings. When the value of the `scope` input matches one of these strings, the _`key-name`_ environment variable and output will be set to _`key-value`_. The scope value comparison is _not_ case sensitive.
 
-#### `key-value`
+#### _`key-value`_
 
-The value that the environment variable will be set to if it's found to meet the scope criteria.
+The value that the environment variable and output will be set to if the scope is found in the _`scope-array`_.
 
 This set of environment variable or input file entries:
 
@@ -142,10 +145,30 @@ env:
   db_server@stage prod: db-server.domain.com
 ```
 
-Produces an environment variable, `${{ env.db_server }}`, with a value of `db-server.domain.com`, if the action `scope` is set to `stage`.
+Produces an environment variable, `${{ env.db_server }}`, with a value of `db-server.domain.com`, if the action's `scope` is set to `stage` or `prod`.
+
+#### Input Environment Variables
+
+When using environment variables for input, this action looks at all current environment variables. They could have been exported by a previous step, or set for the job or workflow. _Any_ environment variable with an `@` in it's name is used as a possible candidate for scoped output.
+
+GitHub actions expressions can be used in the _`key-value`_ when supplying input environment variables in the step's `env` block as in the following example:
+
+```yaml
+      - name: Build DB Connection
+        uses: im-open/set-environment-variables-by-scope@v1.1.4
+        with:
+          scope: ${{ needs.setup.outputs.env-scope }}
+        env:
+          SQL_CONNECTION_STRING@dev: 'Data Source=dev.sql-server.domain.com;Initial Catalog=dev-demo-db;User Id=dev-db-sa-user;Password=${{ secrets.SQL_USER_SECRET }};'
+          SQL_CONNECTION_STRING@qa: 'Data Source=qa.sql-server.domain.com;Initial Catalog=qa-demo-db;User Id=qa-db-sa-user;Password=${{ secrets.SQL_USER_SECRET }};'
+          SQL_CONNECTION_STRING@stage: 'Data Source=stage.sql-server.domain.com;Initial Catalog=stage-demo-db;User Id=stage-db-sa-user;Password=${{ secrets.SQL_USER_SECRET }};'
+          SQL_CONNECTION_STRING@prod: 'Data Source=sql-server.domain.com;Initial Catalog=demo-db;User Id=db-sa-user;Password=${{ secrets.SQL_USER_SECRET }};'
+```
+
+** Note the resulting environment variables this step will set aren't yet available to expressions in the step's own `env` block.** The resulting environment variables are not available until the next step in the job. If you need scoped variable values to be based on the values of other scoped variables you can use this action in consecutive steps.
 
 #### Input File Format
-The contents of an `input-file` is YAML based and has all the elements at the root level.  It's contents would be formatted like this:
+The `input-file` must be YAML format and has all the elements at the root level.  It's contents would be formatted like this:
 
 ```yaml
 db_server@dev qa: lower-env.db-server.domain.com
@@ -161,37 +184,12 @@ something.used.in.build@stage: stage-value
 something.used.in.build@prod: prod-value
 ```
 
+**Note that _`key-value`_\s in input files do _not_ support GitHub action expressions, unlike envrionment variables described previously.**
+
 #### `error-on-no-match`
 
 `error-on-no-match` is intended to alert that no env or output variable has been found based on the input scope. This is beneficial in troubleshooting if a scope *should* produce some form of output. Also a warning will show for any keys that have been included but doesn't provide a value for the input scope criteria.
 
-#### Repository Secrets
-
-Repository secrets can be used with the environment variable creation action, but only through environment vars.  This is because the input file does not receive any secret replacement parsing during the action execution.
-
-An example of this would be the inclusion of a secret and user id in a SQL connection string:
-
-```yaml
-
-jobs:
-  deploy-db:
-    runs-on: [ubuntu-20.04]
-    environment: ${{ needs.setup.outputs.env-scope }}
-
-    steps:
-      - name: Build DB Connection
-        uses: im-open/set-environment-variables-by-scope@v1.1.4
-        with:
-          scope: ${{ needs.setup.outputs.env-scope }}
-        env:
-          SQL_CONNECTION_STRING@dev: 'Data Source=dev.sql-server.domain.com;Initial Catalog=dev-demo-db;User Id=dev-db-sa-user;Password=${{ env.SQL_USER_SECRET }};'
-          SQL_CONNECTION_STRING@qa: 'Data Source=qa.sql-server.domain.com;Initial Catalog=qa-demo-db;User Id=qa-db-sa-user;Password=${{ env.SQL_USER_SECRET }};'
-          SQL_CONNECTION_STRING@stage: 'Data Source=stage.sql-server.domain.com;Initial Catalog=stage-demo-db;User Id=stage-db-sa-user;Password=${{ env.SQL_USER_SECRET }};'
-          SQL_CONNECTION_STRING@prod: 'Data Source=sql-server.domain.com;Initial Catalog=demo-db;User Id=db-sa-user;Password=${{ env.SQL_USER_SECRET }};'
-```
-
-If the scope of `QA` were specified, an environment variable `SQL_CONNECTION_STRING` with the specified value containing a replacement for the `SQL_USER_SECRET` from GitHub Repository's `QA` secret environment.
-
 ## Contributing
 
 When creating new PRs please ensure:
@@ -243,6 +241,6 @@ This project has adopted the [im-open's Code of Conduct](https://github.com/im-o
 
 ## License
 
-Copyright &copy; 2021, Extend Health, LLC. Code released under the [MIT license](LICENSE).
+Copyright &copy; 2023, Extend Health, LLC. Code released under the [MIT license](LICENSE).
 
 [git-version-lite]: https://github.com/im-open/git-version-lite
