Skip to content

A GitHub action to replace tokens in a file, similar to envsubst

License

Notifications You must be signed in to change notification settings

jonlabelle/replace-tokens-action

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Replace Tokens Action

test latest release

A GitHub action to replace tokens in a file, similar to envsubst.

Table of contents

Usage

See action.yml

name description type required default example
paths Token file paths 1 string true none ./prod.json
style Token style/format string false mustache envsubst
filter Filter pattern 2 string false none *.json
exclude Exclusion patterns 3 string false none *dev*.json
recurse Recurse directories boolean false false false
depth Depth of recursion number false none 2
follow-symlinks Follow symbolic links boolean false false false
fail Fail if no tokens replaced boolean false false false
encoding File encoding string false utf8 unicode
no-newline No newline at end-of-file boolean false false true

Examples

Replace tokens in path

Replace mustache styled tokens {{ NAME }} in ./path/to/template.json with environment variable NAME.

steps:
  - name: Replace tokens in the specified path
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: ./path/to/template.json
    env:
      NAME: jon

Note

To avoid issues, it's good practice to treat environment variables as case sensitive, irrespective of the behavior of the operating system and shell you are using.

Using a path filter

Search and replace all tokens in *.json files found in the ./path/to/search directory.

steps:
  - name: Replace tokens using a path filter
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: ./path/to/search
      filter: '*.json'
    env:
      NAME: jon

Search multiple paths

Search three paths and replace matching tokens in *.json* files.

steps:
  - name: Search multiple paths
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: |
        ./first/path
        ./second/path
        ./third/path
      filter: '*.json'
    env:
      NAME: jon

Replace envsubst and make styled tokens

Replace tokens using the envsubst style/format, e.g. ${VARIABLE}.

steps:
  - name: Replace envsubst styled tokens
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: ./path/to/search
      filter: '*.json'
      style: envsubst
    env:
      NAME: jon

Replace tokens using the make style/format, e.g. $(VARIABLE).

steps:
  - name: Replace envsubst styled tokens
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: ./path/to/search
      filter: '*.json'
      style: make
    env:
      NAME: jon

Search paths recursively

Search and replace tokens from the specified paths, recursively, two directories deep.

steps:
  - name: Replace tokens using recursion, 2 directories deep
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: |
        ./first/path/to/search
        ./second/path/to/search
      filter: '*.json'
      recurse: true
      depth: 2
    env:
      NAME: jon

Replace an API key and URL in .env files

Replace URL and API key tokens in .env files.

steps:
  - name: Replace an API key and URL in .env files
    uses: jonlabelle/replace-tokens-action@v1
    with:
      # matches: `./src/.env` and `./src/.env.production`
      paths: ./src
      filter: '*.env*'
    env:
      API_KEY: ${{ secrets.api-key }}
      API_URL: https://example.net/api

Exclude items and patterns

Exclude certain file or directory patterns from results.

steps:
  - name: Exclude certain items or patterns from results
    uses: jonlabelle/replace-tokens-action@v1
    with:
      # matches: `./src/.env.local` and `./src/.env.production`,
      # but not `./src/.env` or `./src/.env.development`
      paths: ./src
      filter: '*.env*'
      exclude: |
        .env
        .env.development
    env:
      API_KEY: ${{ secrets.api-key }}
      API_URL: https://example.net/api

Fail on no-op

Fail the step if no tokens were replaced.

steps:
  - name: Fail if no tokens were replaced
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: ./path/to/search
      filter: '*.json'
      fail: true
    env:
      NAME: jon

Note

A warning will be printed to console output if a token doesn't have a matching environment variable.

Custom file encoding

Specify the encoding to use for file read/writes.

steps:
  - name: Set a non-default encoding option for reading/writing files
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: ./path/to/search
      filter: '*.json'
      encoding: unicode
    env:
      NAME: jon

No newline at eof

Don't insert a final newline after tokens are replaced.

steps:
  - name: Don't insert a newline at the end of the file
    uses: jonlabelle/replace-tokens-action@v1
    with:
      paths: ./path/to/search
      filter: '*.json'
      no-newline: true
    env:
      NAME: jon

Token style

Tokens must be in one of following formats to be replaced:

name style examples
mustache (default) {{ VARIABLE }} {{TOKEN}}, {{ TOKEN }}
envsubst ${VARIABLE} ${TOKEN}
make $(VARIABLE) $(TOKEN)

Where VARIABLE has a matching environment variable name whose value will be used in token replacement. Similar to envsubst(1).

File encoding

The default file encoding for read/write operations is set to utf8, without the byte order mark (BOM). The following additional file encoding formats are supported.

  • utf8: Encodes in UTF-8 format, without the Byte Order Mark (BOM)
  • utf8BOM: Encodes in UTF-8 format with Byte Order Mark (BOM)
  • ascii: Uses the encoding for the ASCII (7-bit) character set
  • ansi: Uses the encoding for the for the current culture's ANSI code page
  • bigendianunicode: Encodes in UTF-16 format using the big-endian byte order
  • bigendianutf32: Encodes in UTF-32 format using the big-endian byte order
  • oem: Uses the default encoding for MS-DOS and console programs
  • unicode: Encodes in UTF-16 format using the little-endian byte order
  • utf32: Encodes in UTF-32 format

License

MIT

Footnotes

  1. A path to one or more locations. Wildcards are accepted. The default location is the current directory (.). Specify multiple paths on separate lines using a multiline string |.

  2. filter only supports * and ? wildcards.

  3. One or more string items or patterns to be matched, and excluded from the results. Wildcard characters are accepted. Specify multiple exclusions on separate lines using a multiline string |. See Microsoft's Get-ChildItem -Exclude docs for more information.