Use variable substitution with GitHub Actions

Learn how to use variable substitution action to replace values in XML, JSON and YAML based configuration and parameter files.

Variable substitution lets you insert values, including GitHub secrets, into files in your repository during the workflow run. For example, you could insert an API login and password into a JSON file during the workflow run.

Variable substitution only works for keys predefined in the object hierarchy. You cannot create new keys with variable substitution. In addition, only variables defined as environment variables in the workflow or system variables that are already available can be used for substitution.


  • A GitHub account. If you don't have one, sign up for free.

Use the variable substitution action

This example walks through replacing values in employee.json using the variable substitution action.

  1. Create employee.json at the root level of your repository.

        "first-name": "Toni",
        "last-name": "Cranz",
        "username": "",
        "password": "",
        "url": ""
  2. Open your GitHub repository and go to Settings.

    Select Settings in the navigation

  3. Select Security > Secrets and variables > Actions.

  4. Select New repository secret.

  5. Add a new secret PASSWORD with the value 5v{W<$2B<GR2=t4# (or a password you select). Save your secret.

  6. Go to Actions and select set up a workflow yourself.

  7. Add a workflow file. The username value in your json file will be replaced with tcranz. The password will be replaced with your GitHub secret. The url field will be populated with a URL that includes the GitHub variable github.repository.

    on: [push]
    name: variable substitution in json
        runs-on: ubuntu-latest
        - uses: actions/checkout@v2
        - uses: microsoft/variable-substitution@v1 
            files: 'employee.json'
            username: tcranz
            password: ${{ secrets.PASSWORD }}
  8. Go to Actions to see your workflow run. Open the variable substitution action. You should see that each variable was replaced.

    SubstitutingValueonKeyWithString username tcranz
    SubstitutingValueonKeyWithString password ***
    SubstitutingValueonKeyWithString url
    Successfully updated file: employee.json

Clean up resources

Delete your GitHub repository when it is no longer needed.

Next steps