substitute-action

GitHub Action to substitute environment variables in files.

Tested on Linux, macOS, and Windows runners.

Features

• Supports $VARIABLE or ${VARIABLE} syntax to specify variables in input files.
• Allows multiple .env files in addition to the env context.
• Allows nested use of variables in .env files from previously listed files and the env context.
• Supports multiline values but format-specific escaping is not supported. Any multiline substitution resulting in an ill-formed file e.g. JSON, YAML, etc. is the responsibility of the end user.
• Multiple input files are allowed for substitution.
• Supports filtering of the env vars by their full names and/or prefixes.
• By default, in-place substitution is performed.
• By disabling the default in-place substitution, newly substituted files are generated with .env suffixes in the same directory.
• These newly generated .env files may be routed to a different path by configuring an output directory. The output directory path will be created if it does not exist.
• Supports dumping of updated/generated files to STDOUT for debugging purposes.

Flow Diagram

flowchart TD
    A(env) --> |export .env files| B(env-files)
    B --> |select listed env vars| C(variables)
    B --> |select prefixed env vars| D(prefixes)
    C --> |substitute| E(input-files)
    D --> |substitute| E(input-files)
    E --> |"[enable-in-place: true]"| F(updated files)
    E --> |"[enable-in-place: false]"| G(new output files with .env suffix)
    G --> |move if configured| I(output-directory)
    F --> |"[enable-dump: true]"| J(STDOUT)
    G --> |"if not moved [enable-dump: true]"| J
    I --> |"[enable-dump: true]"| J

Loading

Usage

Inputs

Input	Required	Default	Description
env-files	false		List of .env files containing VARIABLE=VALUE per line
input-files	true		List of input files to substitute environment variables
variables	false		List of variables to substitute; the rest is ignored
prefixes	false		List of prefixes to select env vars in addition to variables
output-directory	false		Output directory path when enable-in-place: false
enable-in-place	false	true	Enable/disable in-place substitution
enable-dump	false	false	Enable/disable dumping of updated/generated files

Examples

In the following examples, for these sample input files:

input.json

{
  "ENV_VAR": "$ENV_VAR",
  "ENV_VAR1": "$ENV_VAR1",
  "ENV_VAR2": "$ENV_VAR2",
  "ENV_VAR3": "$ENV_VAR3",
  "TEST_VAR": "$TEST_VAR",
  "TEST_VAR1": "$TEST_VAR1",
  "TEST_VAR2": "$TEST_VAR2",
  "SAMPLE_VAR": "$SAMPLE_VAR"
}

input.yaml

ENV_VAR: "${ENV_VAR}"
ENV_VAR1: "${ENV_VAR1}"
ENV_VAR2: "${ENV_VAR2}"
ENV_VAR3: "${ENV_VAR3}"
TEST_VAR: "${TEST_VAR}"
TEST_VAR1: "${TEST_VAR1}"
TEST_VAR2: "${TEST_VAR2}"
SAMPLE_VAR: "${SAMPLE_VAR}"

Only the available variables are substituted with their respective values specified by $VARIABLE or ${VARIABLE}.

Substitute env vars from env

- uses: iamazeem/substitute-action@v1
  env:
    ENV_VAR1: 'env_val1'
    ENV_VAR2: 'env_val2'
  with:
    input-files: |
      input.json
      input.yaml

Substitute env vars with env and env-files

- uses: iamazeem/substitute-action@v1
  env:
    ENV_VAR1: 'env_val1'
    ENV_VAR2: 'env_val2'
  with:
    env-files: |
      env-file1.env
      env-file2.env
    input-files: |
      input.json
      input.yaml

Substitute env vars with variables

- uses: iamazeem/substitute-action@v1
  env:
    ENV_VAR1: 'env_val1'
    ENV_VAR2: 'env_val2'
    ENV_VAR3: 'env_val3'            # Ignored
  with:
    variables: |
      ENV_VAR1
      ENV_VAR2
    input-files: |
      input.json
      input.yaml

Substitute env vars with prefixes

- uses: iamazeem/substitute-action@v1
  env:
    ENV_VAR: 'env_val'
    TEST_VAR: 'test_val'            # Ignored
    SAMPLE_VAR: 'sample_val'        # Ignored
  with:
    prefixes: |
      ENV
    input-files: |
      input.json
      input.yaml

Substitute env vars with variables and prefixes

- uses: iamazeem/substitute-action@v1
  env:
    ENV_VAR1: 'env_val1'
    ENV_VAR2: 'env_val2'            # Ignored
    ENV_VAR3: 'env_val3'            # Ignored
    TEST_VAR1: 'test_val1'
    TEST_VAR2: 'test_val2'
  with:
    variables: |
      ENV_VAR1
    prefixes: |
      TEST_VAR
    input-files: |
      input.json
      input.yaml

Contribute

You may create issues to report bugs or propose new features and enhancements.

PRs are always welcome. Please follow this workflow for submitting PRs:

• Fork the repo.
• Check out the latest main branch.
• Create a feature or bugfix branch from main.
• Commit and push changes to your forked repo.
• Make sure to add tests. See CI.
• Lint and fix Bash issues with shellcheck online or with vscode-shellcheck extension.
• Lint and fix README Markdown issues with vscode-markdownlint extension.
• mermaid.js has been used to create the flow diagram. See its flowchart syntax to update the flow diagram if required.
• Submit the PR.

License

MIT