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.

Table of Contents

• JSON to Variables Setter
  • Overview
  • Table of Contents
  • Supported GitHub Actions Matrix Components
  • Usage
    • Action Configuration
    • Inputs
    • Outputs
  • Examples
    • Variable Reference Examples
    • 1. Basic Usage (Within Same Job)
    • 2. Cross-Job Usage (Using needs Context)
    • 3. Advanced Shell Processing
  • Language-specific Workflows
  • License

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:

• Python: python_test.yml
• Node.js: nodejs_test.yml
• Ruby: ruby_test.yml
• Go: go_test.yml
• Rust: rust_test.yml

License

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