Skip to content

Latest commit

 

History

History
161 lines (112 loc) · 5.44 KB

README.md

File metadata and controls

161 lines (112 loc) · 5.44 KB
Raw

Action Build and Test

Env Var Files

The action imports variables defeined in files (plain text, json, yaml) into the GitHub workflow env variable set.

It provides the following benefits :

  • centralize variable definitions in the source control
  • share variables between different workflows/jobs
  • share variables between your app code and the github workflows

For more information on github action variables please check Variables

Inputs

Name Required Description Default Value
paths Yes The paths of files that contain the definitions of the variable ./project.vars.properties
override No When set to true, the processing will override the already defined vars in the job with the values read from file false
select No When non empty, the parameter indicates the list of the variables to import from the fileset. In that case only the listed variables will be imported, other discovered varaibles will be ignored. When empty all discovered variables will be imported ''
separator No Override the default separator for nested properties that can be part of structured files (json, yaml) '_'

Supported Formats

This version supports variables defied from plain text and json files.

The format will be determined by the file extensions :

  • JSON : .json
  • YAML : .yaml, .yml
  • Plain Text : all but .json, .yml and .yaml

Plain Text Files

Plain text files (.properties, .conf, .whaever ) expect to provide key=value definitions such as :

VariableName=Value

Note that the parser will ignore all lignes starting with standard scripting ("#") and Java/JS ("//", "/*" , " * " , "*/") comments. It will also remove all trailig spaces from the line.

For instance the following variable definitions file will inject a variable named VariableName with the value 'New Value' :

# old definition
# VariableName=OldValue
# this is the current variable definition
 VariableName = New Value

JSON Files

The action supports JSON files and handles nested properties declaration.

Nested properties will be separated by an underscore ("_") before injection.

For instance, the following JSON content :

{ 
 "build" : { 
  "version" : {
   "major" : "1",
   "minor" : "0",
   "patch" : "42"
    }
  }
}

will inject the following variables :

build_version_major=1
build_version_minor=0
build_version_patch=42

Please note that the parser will only process fully compliant JSON object declarations ( i.e : { "K" : "V" } ).

The parsing of lists of objects such as { [ {"build" : "always" } , { "tag" : "latest" } ] } is not supported.

YAML Files

The action supports JSON files and handles nested properties declaration.

Nested properties will be separated by an underscore ("_") before injection.

For instance, the following YAML content :

build:
  version:
    major: "1"
    minor: "2"

will inject the following variables :

build_version_major=1
build_version_minor=2

Known issues

The parsing of the structured formats (JSON and YAML) does not support correctly variables with array values.

Consider the following example files :

{ "envs" : [ "dev" , "test", "prod "]}
envs:
  - dev
  - test
  - prod

In the current state, the above mentionned payloads parsing will create the following vars :

envs_1:dev
envs_2:test
envs_3:prod

Whenever possible we advise to consider an alternative declaration for listed values and to post process them.

For instance the above example should be written as :

{ "envs" : "dev,test,prod" }

Example usages

In order to import all vars from a single file, simply use :

  - name: Import vars example
    uses: zlatko-ms/varfiletoenv@v3
    with:
      paths: ./path/to/my/file.properties

All usages are illustrated by the integration tests implemented in the main action workflow directory.

Here is a selection of the common usages :

Use Case Description Link
Load from multiple files Load variables from multiple files and formats view
Override existing values Override the values of already defined variables view
Select variables Load or override only variables that are specified in the selector view
Change nested separator Loaded nested variables using a specific separator instead of the default "_" view

When copying/pasting from the examples, remember to replace the @main tag by the release tag [ currently @v3 ].