Define YAML document, filter it with JSON query and get result as outputs

Introduction

Utility action allow to declare YAML structured document as an input and get it's part as the action outputs referenced using JQ.

This action is useful in simplifing complext GitHub action workflows in different ways. For examples follow usage section.

Example

• query: .true replace with query: ."true"
• query: .${{ inputs.from == '' }} replace with query: ."${{ inputs.from == '' }}"

Usage

Define constants

  name: Pull Request
  on:
    pull_request:
      branches: [ 'main' ]
      types: [opened, synchronize, reopened, closed, labeled, unlabeled]

  jobs:
    demo:
      runs-on: ubuntu-latest
      steps:
        - name: Context
          id: context
          uses: step-security/github-action-yaml-config-query@v1
          with:
            config: |
              image: acme/example
              tag: sha-${{ github.sha }}

        - run: |
          docker run ${{ steps.context.outputs.image }}:${{ steps.context.outputs.tag }}

Implement if/else

  name: Promote
  on:
    workflow_call:
      inputs:
        from:
          required: false
          type: string

  jobs:
    demo:
      runs-on: ubuntu-latest
      steps:
        - name: Context
          id: from
          uses: step-security/github-action-yaml-config-query@v1
          with:
            query: ."${{ inputs.from == '' }}"
            config: |-
              true:
                tag: ${{ github.sha }}
              false:
                tag: ${{ inputs.from }}

        - run: |
          docker tag acme/example:${{ steps.context.outputs.tag }}

Implement switch

name: Build
on:
  pull_request:
    branches: ['main']
    types: [opened, synchronize, reopened]
  push:
    branches: [main]
  release:
    types: [published]

jobs:
  context:
    runs-on: ubuntu-latest
    steps:
      - name: Context
        id: controller
        uses: step-security/github-action-yaml-config-query@v1
        with:
          query: .${{ github.event_name }}
          config: |-
            pull_request: 
              build: true
              promote: false
              test: true
              deploy: ["preview"]
            push:
              build: true
              promote: false  
              test: true
              deploy: ["dev"]
            release:
              build: false
              promote: true
              test: false
              deploy: ["staging", "production"]
    outputs:
      build: ${{ steps.controlle.outputs.build }}
      promote: ${{ steps.controlle.outputs.promote }}
      test: ${{ steps.controlle.outputs.test }}
      deploy: ${{ steps.controlle.outputs.deploy }}

  build:
    needs: [context]
    if: ${{ needs.context.outputs.build }}
    uses: ./.github/workflows/reusable-build.yaml

  test:
    needs: [context, test]
    if: ${{ needs.context.outputs.test }}
    uses: ./.github/workflows/reusable-test.yaml

  promote:
    needs: [context]
    if: ${{ needs.context.outputs.promote }}
    uses: ./.github/workflows/reusable-promote.yaml

  deploy:
    needs: [context]
    if: ${{ needs.context.outputs.deploy != '[]' }}
    strategy:
      matrix:
        environment: ${{ fromJson(needs.context.outputs.deploy) }}
    uses: ./.github/workflows/reusable-deploy.yaml
    with:
      environment: ${{ matrix.environment }}

Inputs

Name	Description	Default	Required
config	YAML config	N/A	true
query	JQ Query	.	true

References

For additional context, refer to some of these links.

• github-actions-workflows - Reusable workflows for different types of projects
• example-github-action-release-workflow - Example application with complicated release workflow

For 🐛 bug reports & feature requests, please use the issue tracker.

Complete license is available in the LICENSE file.

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

Trademarks

All other trademarks referenced herein are the property of their respective owners.

---

Copyright © 2017-2026 Cloud Posse, LLC

Copyright © 2026 StepSecurity