You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+60-63Lines changed: 60 additions & 63 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,20 +1,19 @@
1
1
# Set Environment Variables by Scope
2
2
3
-
This action takes specially formatted environment variablesand/or an input file to emit scoped environment variables.
3
+
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.
|`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 |
29
-
|`input-file`| false | A specially formatted YAML file containing possible environment variable candidates with their associated scopes |
30
-
|`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 |
31
-
|`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 |
32
-
|`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 |
33
-
34
-
### Environment Variables
35
-
36
-
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.
|`scope`| true | The scope is used to identify which value to select for each key name. See the usage instructions below. |
28
+
|`input-file`| false | A specially formatted YAML file containing possible environment variable candidates with their associated scopes. |
29
+
|`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. |
30
+
|`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. |
31
+
|`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 |
37
32
38
33
## Outputs
39
34
40
-
Varies by usage, but is based on [`key-name`](#key-name) specified in environment variables and the `input-file` specified.
35
+
Varies by usage, but is based on the [`key-name`](#key-name)s supplied in environment variables and the `input-file`.
41
36
42
37
## Usage Examples
43
38
@@ -47,9 +42,16 @@ Varies by usage, but is based on [`key-name`](#key-name) specified in environmen
custom_error_message: 'The environment must be Dev, QA, Stage or Prod'
69
71
env:
70
-
ENVIRONMENT@dev d development: dev
71
-
ENVIRONMENT@qa a: qa
72
-
ENVIRONMENT@stage s stg: stage
73
-
ENVIRONMENT@prod p production: prod
72
+
ENVIRONMENT@dev: dev
73
+
ENVIRONMENT@qa: qa
74
+
ENVIRONMENT@stage stage-secondary: stage
75
+
ENVIRONMENT@prod prod-secondary: prod
74
76
75
77
- run: echo "The current environment is ${{ env.ENVIRONMENT }}."
76
78
@@ -116,23 +118,23 @@ inFileName2@dev qa stage prod demo: 'file value for all environments'
116
118
117
119
### Usage Instructions
118
120
119
-
The format of the `env` variable and the `input-file` contents are the same and follows this format:
121
+
The format of each input environment variable and each entry in the `input-file` are the same and follows this format:
120
122
121
123
`[key-name]@[scope-array]: [key-value]`
122
124
123
-
#### `key-name`
125
+
#### _`key-name`_
124
126
125
-
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.
127
+
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.
126
128
127
-
**_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.
129
+
**_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.
128
130
129
-
#### `scope-array`
131
+
#### _`scope-array`_
130
132
131
-
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.
133
+
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.
132
134
133
-
#### `key-value`
135
+
#### _`key-value`_
134
136
135
-
The value that the environment variable will be set to if it's found to meet the scope criteria.
137
+
The value that the environment variable and output will be set to if the scope is found in the _`scope-array`_.
136
138
137
139
This set of environment variable or input file entries:
138
140
@@ -142,10 +144,30 @@ env:
142
144
db_server@stage prod: db-server.domain.com
143
145
```
144
146
145
-
Produces an environment variable, `${{ env.db_server }}`, with a value of `db-server.domain.com`, if the action `scope` is set to `stage`.
147
+
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`.
148
+
149
+
#### Input Environment Variables
150
+
151
+
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.
152
+
153
+
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:
** 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.
146
168
147
169
#### Input File Format
148
-
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:
170
+
The `input-file` must be YAML format and has all the elements at the root level. It's contents would be formatted like this:
**Note that _`key-value`_\s in input files do _not_ support GitHub action expressions, unlike envrionment variables described previously.**
187
+
164
188
#### `error-on-no-match`
165
189
166
190
`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.
167
191
168
-
#### Repository Secrets
169
-
170
-
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.
171
-
172
-
An example of this would be the inclusion of a secret and user id in a SQL connection string:
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.
194
-
195
192
## Contributing
196
193
197
194
When creating new PRs please ensure:
@@ -243,6 +240,6 @@ This project has adopted the [im-open's Code of Conduct](https://github.com/im-o
0 commit comments