Skip to content

JSON to Variables Setter

GitHub Marketplace Docs License: MIT
Test on PR Python
uv Ruff Checked with mypy ty typos pre-commit
zizmor gitleaks

Overview

JSON to Variables Setter (json2vars-setter) is a GitHub Action that parses a JSON file and sets its values as output variables in GitHub Actions workflows. This action streamlines the management of matrix testing configurations and other workflow variables, making your CI/CD processes more maintainable and adaptable.

By centralizing your configuration in JSON files, you gain the ability to easily manage and update testing environments across multiple workflows, reducing duplication and maintenance overhead.

Key Features

  • JSON Parsing: Convert JSON files into GitHub Actions output variables for use in your workflows
  • Dynamic Version Management: Automatically update your testing matrix with latest language versions from official sources
  • Version Caching: Cache version information to reduce API calls and improve workflow performance
  • Support for Multiple Languages: Compatible with Python, Ruby, Node.js, Go, Rust, PHP, .NET (C#), Java, Deno, Bun, Zig, Elixir, Dart, and Swift
  • Flexible Configuration: Maintain a single source of truth for your matrix testing environments

Supported Matrix Components

Languages Actions Example Test Status
Python setup-python Python Test
Ruby setup-ruby Ruby Test
Node.js setup-node Node.js Test
Go setup-go Go Test
Rust rust-toolchain Rust Test
PHP setup-php PHP Test
.NET setup-dotnet .NET Test
Java setup-java Java Test
Deno setup-deno Deno Test
Bun setup-bun Bun Test
Zig setup-zig Zig Test
Elixir setup-beam Elixir Test
Dart setup-dart Dart Test
Swift setup-swift Swift Test
Julia setup-julia Julia Test
Crystal install-crystal Crystal Test
Haskell setup-haskell Haskell Test
OCaml setup-ocaml OCaml Test
Kotlin kotlin-compiler Kotlin Test
Clang/LLVM setup-cpp Clang Test
GCC setup-cpp GCC Test
Flutter flutter-action Flutter Test

📖 Per-language details — supported OS, versions, and the setup action each example drives — are in the Languages section.

Sample Workflows

Beyond the per-language tests above, these runnable use-case samples live in the repository and execute on real GitHub Actions. The green badge is proof you can reproduce the result, then copy the files into your own project — no local setup required to gain confidence.

Use case Status What it demonstrates Files
Single source of truth Sample: Single Source of Truth One JSON parsed once, then consumed by an independent test matrix and a separate lint job — define versions in one place, use them everywhere workflow README
Monorepo Sample: Monorepo Several projects in one repo, each with its own matrix JSON (Python backend + Node.js frontend) and an independent test matrix workflow README
Template from cache Sample: Template (cache) Generate a matrix from an existing version cache with no API calls (template-only), trimmed via output-count workflow README
Version cache Sample: Version Cache Drive a multi-version matrix from a committed cache (use-cache) — zero API calls on a cache hit, auto-refresh when cache-max-age is exceeded workflow README
Dynamic update (scheduled) Sample: Dynamic Update Weekly scheduled maintenance: fetch the latest language versions from the live API (update-matrix) and rebuild the matrix — side-effect-free (no commit) workflow README
Conditional matrix Sample: Conditional Matrix Pick the matrix by event — a light, fast matrix on pull requests and the full cross-OS matrix on schedule / dispatch workflow README
Reusable workflow Sample: Reusable Workflow Define the matrix once in a workflow_call library and consume its outputs from a caller — maintain the version set in one place workflow README

Quick Start

See Basic Usage Examples for details.

 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
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

  run_tests:
    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@v7.0.1
        with:
          fetch-depth: 0

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

Components

The action consists of three main components that work together to provide a powerful, flexible solution:

graph TD
    subgraph "JSON to Variables Setter"
        A[JSON to Variables Parser ] -->|Reads| B[Matrix JSON File]
        A -->|Sets| C[GitHub Actions Outputs]

        D[Dynamic Matrix Updater] -->|Updates| B
        D -->|Fetches from| E[GitHub API]

        F[Version Cache Manager] -->|Caches| G[Version Information]
        F -->|Fetches from| E
        F -->|Generates| B
    end

    C -->|Used by| I[GitHub Workflows]

    classDef core fill:#43a047,stroke:#2e7d32,stroke-width:2px,color:#fff
    classDef file fill:#ffca28,stroke:#fb8c00,stroke-width:1px,color:#333333
    classDef output fill:#42a5f5,stroke:#1976d2,stroke-width:1px
    classDef external fill:#78909c,stroke:#546e7a,stroke-width:1px
    classDef api fill:#e91e63,stroke:#c2185b,stroke-width:1px,color:#fff

    class A,D,F core
    class B,G file
    class C output
    class I external
    class E api

  1. JSON to Variables Parser (github_output.py): Core component that parses JSON and converts it to GitHub Actions outputs. Makes your configuration data accessible throughout your workflow.

  2. Dynamic Matrix Updater (matrix_update.py): Updates your matrix configuration with the latest or stable language versions. Ensures your CI/CD tests run against current language versions without manual updates.

  3. Version Cache Manager (version_cache.py): Manages cached version information to optimize API usage. Reduces external API calls by intelligently caching data, improving workflow performance and reliability.

Learn More