GitHub Action to substitute environment variables in files.

This composite action uses standard Bash facilities such as ls, mkdir, mv, if, for, echo, env, envsubst, exit, grep, cut, source, etc.

It is actively being tested on Linux, macOS, and Windows runners. See CI workflow for more details.

• 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.

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

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}.

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

- 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

- 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

- 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

- 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

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.

MIT