JSON to Variables Setter

Overview

JSON to Variables Setter (json2vars-setter) is a GitHub Action designed to parse a JSON file and set the resulting variables (such as operating systems, programming language versions, and GitHub Pages branch) as outputs in a GitHub Actions workflow.

Supported GitHub Actions Matrix Components

Languages	Test Status

Usage

This action reads a JSON file (default path: .github/workflows/matrix.json) and sets GitHub Actions outputs based on the parsed data.

Note

Please create the JSON file by referring to the Examples.
By default, the JSON file path is .github/workflows/matrix.json. If you create a custom file, specify it in the 7rikazhexde/json2vars-setter action.
In the workflow, only the variables specified in the Outputs section are available.
Language versions are optional. If a language is not defined in the JSON, its corresponding output will be empty.

Action Configuration

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@v4.2.2
        with:
          fetch-depth: 0

      - name: Set variables from JSON
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@main
        with:
          json-file: .github/workflows/python_project_matrix.json

Inputs

Input	Description	Required
`json-file`	Path to the JSON file. Default: `.github/workflows/matrix.json`	No

Outputs

Important

In order to reference them in both steps and jobs, outputs must be specified.
Please check the Examples section for details.

Output	Description
`os`	List of operating systems
`versions_python`	List of Python versions
`versions_ruby`	List of Ruby versions
`versions_nodejs`	List of Node.js versions
`versions_go`	List of Go versions
`versions_rust`	List of Rust versions
`ghpages_branch`	GitHub Pages branch name

Examples

This action uses a JSON configuration file (e.g. matrix.json) to define your matrix testing environments.

Complete Configuration Example

{
    "os": [
        "ubuntu-latest",
        "windows-latest",
        "macos-latest"
    ],
    "versions": {
        "python": [
            "3.10",
            "3.11",
            "3.12",
            "3.13"
        ],
        "ruby": [
            "3.0.6",
            "3.1.6",
            "3.2.6"
        ],
        "nodejs": [
            "16",
            "18",
            "20"
        ],
        "go": [
            "1.21.0",
            "1.22.0"
        ],
        "rust": [
            "1.75.0",
            "1.76.0",
            "stable"
        ]
    },
    "ghpages_branch": "gh-pages"
}

You can also create a simplified configuration by including only the languages you need. For example, if your project only uses Python(e.g. python_project_matrix.json).

Tip

Only specify the languages you actually use.
Outputs for undefined languages will be empty arrays.
This helps keep your JSON configuration concise and maintainable.

Simplified Configuration Example

{
    "os": [
        "ubuntu-latest",
        "windows-latest",
        "macos-latest"
    ],
    "versions": {
        "python": [
            "3.10",
            "3.11",
            "3.12",
            "3.13"
        ]
        // Other language versions can be omitted if not used
    },
    "ghpages_branch": "gh-pages"
}

Variable Reference Examples

This section demonstrates various ways to reference the output variables in your workflow.

Tip

For list variables, always remember to use fromJson() when accessing individual elements
When setting list variables in shell scripts, use single quotes (') to preserve the JSON structure
Use jq for complex JSON array manipulations in shell scripts

1. Basic Usage (Within Same Job)

The simplest way to access variables is within the same job using the steps context:

Code 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@v4.2.2
        with:
          fetch-depth: 0

      - name: Set variables from JSON
        id: json2vars
        uses: 7rikazhexde/json2vars-setter@main
        with:
          json-file: .github/workflows/python_project_matrix.json

      - name: Access Variables
        run: |
          # Direct access to list variables from json2vars output
          echo "os: ${{ steps.json2vars.outputs.os }}"
          echo "versions_python: ${{ steps.json2vars.outputs.versions_python }}"

          # Access individual elements from json2vars output
          echo "First OS: ${{ fromJson(steps.json2vars.outputs.os)[0] }}"
          echo "First Python version: ${{ fromJson(steps.json2vars.outputs.versions_python)[0] }}"

          # Access non-list variables from json2vars output
          echo "Branch: ${{ steps.json2vars.outputs.ghpages_branch }}"

Example Output

os: ["ubuntu-latest", "windows-latest", "macos-latest"]
versions_python: ["3.10", "3.11", "3.12", "3.13"]
First OS: ubuntu-latest
First Python version: 3.10
Branch: ghpages

2. Cross-Job Usage (Using needs Context)

To use variables across different jobs, use the needs context and ensure outputs are properly defined in the source job.

Matrix Strategy Usage

  test_job_2:
    needs: set_variables
    strategy:
      matrix:
        os: ${{ fromJson(needs.set_variables.outputs.os) }}
        python-version: ${{ fromJson(needs.set_variables.outputs.versions_python) }}
    runs-on: ${{ matrix.os }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4.2.2
        with:
          fetch-depth: 0
      - name: Set up Python
        uses: actions/setup-python@v5.3.0
        with:
          python-version: ${{ matrix.python-version }}

Variable Access in Job and Steps

  test_job_3:
    needs: set_variables
    # Referenced from output variables from set_variables job (e.g. runs-on: ubuntu-latest)
    runs-on: ${{ fromJson(needs.set_variables.outputs.os)[0] }}
    steps:
      - name: Access Variables
        run: |
          # Non-list variables
          branch="${{ needs.set_variables.outputs.ghpages_branch }}"

          # List variables (note the single quotes)
          os='${{ needs.set_variables.outputs.os }}'
          versions_python='${{ needs.set_variables.outputs.versions_python }}'

          # Individual elements
          first_os="${{ fromJson(needs.set_variables.outputs.os)[0] }}"
          first_version="${{ fromJson(needs.set_variables.outputs.versions_python)[0] }}"

3. Advanced Shell Processing

For more complex operations, you can process the JSON arrays using shell commands with jq.

Processing Arrays in Shell

  test_job_4:
    needs: set_variables
    steps:
      - name: Process Variables
        run: |
          # Convert JSON arrays to space-separated lists
          os_list=$(echo '${{ needs.set_variables.outputs.os }}' | jq -r '.[]' | tr '\n' ' ' | sed 's/ $//')
          versions_list=$(echo '${{ needs.set_variables.outputs.versions_python }}' | jq -r '.[]' | tr '\n' ' ' | sed 's/ $//')

          # Example: Generate combinations
          for os in ${os_list}; do
            for version in ${versions_list}; do
              echo "OS: ${os}, Python Version: ${version}"
            done
          done

Example Output

OS: ubuntu-latest, Python Version: 3.10
OS: ubuntu-latest, Python Version: 3.11
OS: ubuntu-latest, Python Version: 3.12
OS: ubuntu-latest, Python Version: 3.13
OS: windows-latest, Python Version: 3.10
OS: windows-latest, Python Version: 3.11
OS: windows-latest, Python Version: 3.12
OS: windows-latest, Python Version: 3.13
OS: macos-latest, Python Version: 3.10
OS: macos-latest, Python Version: 3.11
OS: macos-latest, Python Version: 3.12
OS: macos-latest, Python Version: 3.13

Language-specific Workflows

For language-specific workflow examples, please refer to:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GitHub Action

JSON to Variables Setter