JSON in GitHub Actions: Parsing, fromJSON, and Dynamic Matrices

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

GitHub Actions uses JSON extensively — for dynamic matrices, step outputs, context objects, and even secrets. The built-in fromJSON() and toJSON() expression functions are the bridge between YAML workflow files and structured data. This guide covers every pattern you'll encounter in real-world CI/CD pipelines.

fromJSON() and toJSON() Expressions

GitHub Actions expressions live in ${{ ... }} delimiters. All values in expressions are strings, booleans, numbers, or null — there are no native objects or arrays unless you explicitly deserialize them.

# toJSON — serialize an object to a string
- name: Dump github context
  run: echo '${{ toJSON(github) }}'

# fromJSON — parse a string into a usable object
- name: Read version from output
  run: echo "Tag is ${{ fromJSON(steps.meta.outputs.json).tags[0] }}"

# Practical: pass structured data between jobs
jobs:
  build:
    outputs:
      config: ${{ toJSON(steps.load.outputs) }}
  deploy:
    needs: build
    steps:
      - run: echo "${{ fromJSON(needs.build.outputs.config).region }}"

toJSON() is most useful for debugging — dump the entire github, runner, or job context to understand what data is available. fromJSON() is the workhorse for consuming structured data in expressions.

Dynamic Job Matrices

Static matrices in strategy.matrix are defined inline. Dynamic matrices compute the values at runtime — useful for testing against versions read from a config file, or deploying to environments defined in a JSON file checked into the repo.

# versions.json (checked into repo)
["18", "20", "22"]

# .github/workflows/test.yml
jobs:
  generate-matrix:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: set-matrix
        run: echo "matrix=$(cat versions.json | jq -c .)" >> $GITHUB_OUTPUT

  test:
    needs: generate-matrix
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

The output must be a compact, single-line JSON array. jq -c . compacts any JSON input. The consumer job must declare needs: [generate-matrix] and reference the output with the exact variable name.

Dynamic Matrix with Objects

# environments.json
[
  {"env": "staging", "url": "https://staging.example.com", "region": "us-east-1"},
  {"env": "production", "url": "https://example.com", "region": "us-west-2"}
]

# Workflow
strategy:
  matrix:
    include: ${{ fromJSON(needs.gen.outputs.matrix) }}
steps:
  - name: Deploy
    run: |
      echo "Deploying to ${{ matrix.env }} at ${{ matrix.url }}"
      aws --region ${{ matrix.region }} s3 sync ./dist s3://bucket-${{ matrix.env }}

Parsing Step Outputs

The GITHUB_OUTPUT file stores key-value pairs where values are strings. Writing JSON to it and reading it back with fromJSON() is the standard pattern for passing structured data between steps.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Write JSON to output (compact = single line, safe for GITHUB_OUTPUT)
      - id: meta
        run: |
          DATA=$(jq -c '{
            version: .version,
            name: .name,
            timestamp: now | todate
          }' package.json)
          echo "data=$DATA" >> $GITHUB_OUTPUT

      # Read specific fields
      - name: Tag image
        run: |
          echo "Building version: ${{ fromJSON(steps.meta.outputs.data).version }}"
          docker build -t myapp:${{ fromJSON(steps.meta.outputs.data).version }} .

Multi-line JSON with Delimiter

# For pretty-printed JSON that contains newlines
- id: report
  run: |
    DELIMITER=$(openssl rand -hex 8)
    echo "json<<$DELIMITER" >> $GITHUB_OUTPUT
    jq '.' result.json >> $GITHUB_OUTPUT
    echo "$DELIMITER" >> $GITHUB_OUTPUT

# Read it back
- run: echo '${{ steps.report.outputs.json }}'

Use a random delimiter to avoid collisions with content. However, the fromJSON() expression function requires a string — if you use the heredoc approach, the multi-line JSON string is still valid input for fromJSON().

Using jq in Workflows

jq is pre-installed on ubuntu-latest, macos-latest, and windows-latest runners. It's the most versatile tool for JSON manipulation in shell steps.

# Extract scalar field
VERSION=$(jq -r '.version' package.json)

# Filter array
ACTIVE=$(jq '[.[] | select(.active == true)]' services.json)

# Compact for GITHUB_OUTPUT
echo "matrix=$(jq -c '.services' config.json)" >> $GITHUB_OUTPUT

# Inject shell variable into jq
ENV_CONFIG=$(jq --arg env "$DEPLOY_ENV" '.[$env]' environments.json)

# Transform and combine
PAYLOAD=$(jq -n   --arg version "$VERSION"   --arg sha "${{ github.sha }}"   '{version: $version, commit: $sha, timestamp: now | todate}')

# Conditional exit code (useful with if: steps.check.outcome == 'success')
jq -e '.status == "ok"' result.json

The -r flag removes surrounding quotes from string output. The -e flag makes jq exit with code 1 if the output is false or null — use it with if: steps.X.outcome == 'success' conditions.

Reading package.json in Workflows

Pulling version or other metadata from package.json is one of the most common JSON operations in Node.js CI pipelines.

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - id: pkg
        run: |
          echo "version=$(jq -r '.version' package.json)" >> $GITHUB_OUTPUT
          echo "name=$(jq -r '.name' package.json)" >> $GITHUB_OUTPUT
          echo "node=$(jq -r '.engines.node // ">=18"' package.json)" >> $GITHUB_OUTPUT

      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: v${{ steps.pkg.outputs.version }}
          release_name: ${{ steps.pkg.outputs.name }} v${{ steps.pkg.outputs.version }}

      - name: Build Docker image
        run: |
          docker build             --label "version=${{ steps.pkg.outputs.version }}"             -t ghcr.io/${{ github.repository }}:${{ steps.pkg.outputs.version }} .

JSON Secrets and Config

GitHub Secrets are strings. You can store a JSON object as a single secret — useful for grouping related configuration values.

# Secret value stored in repository settings:
# DB_CONFIG = {"host":"db.prod.example.com","port":5432,"database":"myapp","ssl":true}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Connect to database
        env:
          DB_HOST: ${{ fromJSON(secrets.DB_CONFIG).host }}
          DB_PORT: ${{ fromJSON(secrets.DB_CONFIG).port }}
          DB_NAME: ${{ fromJSON(secrets.DB_CONFIG).database }}
        run: ./scripts/migrate.sh

      # AWS credentials as JSON
      # AWS_CREDS = {"access_key_id":"AKIA...","secret_access_key":"...","region":"us-east-1"}
      - name: Configure AWS
        run: |
          aws configure set aws_access_key_id ${{ fromJSON(secrets.AWS_CREDS).access_key_id }}
          aws configure set aws_secret_access_key ${{ fromJSON(secrets.AWS_CREDS).secret_access_key }}
          aws configure set region ${{ fromJSON(secrets.AWS_CREDS).region }}

Note that jq-extracted values from secrets won't be automatically redacted in logs. Always assign secret fields to env: variables (which GitHub masks) rather than interpolating directly into run: commands.

Common Patterns Reference

FAQ