Skip to content

Basic Usage Examples

This page demonstrates basic usage patterns for the JSON to Variables Setter action. These examples cover common scenarios and provide a foundation for integrating the action into your workflows.

Simple JSON Parsing

The most basic use case is parsing a JSON file to make its values available as GitHub Actions outputs.

Configuration File

First, create a matrix.json file in .github/json2vars-setter/:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "os": [
        "ubuntu-latest",
        "windows-latest",
        "macos-latest"
    ],
    "versions": {
        "python": [
            "3.10",
            "3.11",
            "3.12"
        ]
    },
    "ghpages_branch": "gh-pages"
}

Basic Workflow

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
name: Basic Example

jobs:
  set_variables:
    runs-on: ubuntu-latest
    outputs:
      os: ${{ steps.json2vars.outputs.os }}
      versions_python: ${{ steps.json2vars.outputs.versions_python }}
      ghpages_branch: ${{ steps.json2vars.outputs.ghpages_branch }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Set variables from JSON
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@v1.13.0
        with:
          json-file: .github/json2vars-setter/sample/matrix.json

      - name: Check outputs
        run: |
          echo "Operating Systems: ${{ steps.json2vars.outputs.os }}"
          echo "Python Versions: ${{ steps.json2vars.outputs.versions_python }}"
          echo "GitHub Pages Branch: ${{ steps.json2vars.outputs.ghpages_branch }}"

Matrix Strategy Example

This example demonstrates how to use the parsed values in a matrix strategy for parallel testing.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
name: Matrix Testing

jobs:
  set_variables:
    runs-on: ubuntu-latest
    outputs:
      os: ${{ steps.json2vars.outputs.os }}
      versions_python: ${{ steps.json2vars.outputs.versions_python }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Set variables from JSON
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@v1.13.0
        with:
          json-file: .github/json2vars-setter/sample/matrix.json

  test:
    needs: set_variables
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: ${{ fromJson(needs.set_variables.outputs.os) }}
        python-version: ${{ fromJson(needs.set_variables.outputs.versions_python) }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Set up Python
        uses: actions/setup-python@v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Run tests
        run: |
          python -m pip install --upgrade pip
          pip install pytest
          pytest

Dynamic Update Example

This example shows how to dynamically update your matrix JSON with the latest language versions.

Runnable sample (green badge)

Proven live as Sample - Dynamic Update (files).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
name: Dynamic Matrix Update

jobs:
  build_and_test:
    runs-on: ubuntu-latest
    outputs:
      os: ${{ steps.json2vars.outputs.os }}
      versions_python: ${{ steps.json2vars.outputs.versions_python }}
      versions_nodejs: ${{ steps.json2vars.outputs.versions_nodejs }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Set variables with dynamic update
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@v1.13.0
        with:
          json-file: .github/json2vars-setter/sample/matrix.json
          update-matrix: 'true'
          python-strategy: 'stable'
          nodejs-strategy: 'latest'

      - name: Show updated matrix
        run: |
          echo "Python versions: ${{ steps.json2vars.outputs.versions_python }}"
          echo "Node.js versions: ${{ steps.json2vars.outputs.versions_nodejs }}"

  test_python:
    needs: build_and_test
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ${{ fromJson(needs.build_and_test.outputs.versions_python) }}

    steps:
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Check Python version
        run: python --version

Version Caching Example

This example demonstrates how to use the version caching feature to reduce API calls.

Runnable sample (green badge)

Proven live as Sample - Version Cache (files).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
name: Cached Version Matrix

jobs:
  set_variables:
    runs-on: ubuntu-latest
    outputs:
      os: ${{ steps.json2vars.outputs.os }}
      versions_python: ${{ steps.json2vars.outputs.versions_python }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Set variables with cached versions
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@v1.13.0
        with:
          json-file: .github/json2vars-setter/sample/matrix.json
          use-cache: 'true'
          cache-max-age: '7'  # Update cache if older than 7 days
          cache-languages: 'python'
          keep-existing: 'true'

      - name: Show cached versions
        run: |
          echo "Python versions: ${{ steps.json2vars.outputs.versions_python }}"

Custom Matrix Configuration

This example shows how to use a custom matrix configuration file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
name: Custom Matrix Configuration

jobs:
  set_variables:
    runs-on: ubuntu-latest
    outputs:
      os: ${{ steps.json2vars.outputs.os }}
      versions_python: ${{ steps.json2vars.outputs.versions_python }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Set variables from custom JSON
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@v1.13.0
        with:
          json-file: .github/json2vars-setter/sample/python_project_matrix.json

      - name: Show configured versions
        run: |
          echo "Python versions: ${{ steps.json2vars.outputs.versions_python }}"

With custom matrix file .github/json2vars-setter/python_project_matrix.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "os": [
        "ubuntu-latest"
    ],
    "versions": {
        "python": [
            "3.9",
            "3.10",
            "3.11"
        ]
    }
}

Multiple Language Example

This example demonstrates testing with multiple programming languages configured in the matrix.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
name: Multi-language Tests

jobs:
  set_variables:
    runs-on: ubuntu-latest
    outputs:
      os: ${{ steps.json2vars.outputs.os }}
      versions_python: ${{ steps.json2vars.outputs.versions_python }}
      versions_nodejs: ${{ steps.json2vars.outputs.versions_nodejs }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Set variables from JSON
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@v1.13.0
        with:
          json-file: .github/json2vars-setter/sample/matrix.json

  test_python:
    needs: set_variables
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ${{ fromJson(needs.set_variables.outputs.versions_python) }}

    steps:
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Run Python tests
        run: |
          python --version
          # ... run your Python tests ...

  test_nodejs:
    needs: set_variables
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: ${{ fromJson(needs.set_variables.outputs.versions_nodejs) }}

    steps:
      - name: Set up Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v7.0.0
        with:
          node-version: ${{ matrix.node-version }}

      - name: Run Node.js tests
        run: |
          node --version
          # ... run your Node.js tests ...

Weekly Matrix Update Example

This example demonstrates how to set up a scheduled workflow to update your matrix weekly.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
name: Weekly Matrix Update

on:
  schedule:
    - cron: '0 0 * * 0'  # Run every Sunday at midnight

jobs:
  update_matrix:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7.0.1

      - name: Update matrix.json
        uses: 7rikazhexde/json2vars-setter@v1.13.0
        with:
          json-file: .github/json2vars-setter/sample/matrix.json
          update-matrix: 'true'
          update-strategy: 'stable'  # Use stable versions for all languages

      - name: Commit changes
        run: |
          git config --local user.email "actions@github.com"
          git config --local user.name "GitHub Actions"
          git add .github/json2vars-setter/matrix.json
          git commit -m "Update testing matrix with latest stable versions" || echo "No changes to commit"
          git push

Next Steps