README.yaml

---
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: github-action-yaml-config-query

# Tags of this project
tags:
  - github-action

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/github-action-yaml-config-query

# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/github-action-yaml-config-query.svg"
    url: "https://github.com/cloudposse/github-action-yaml-config-query/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

related: []

# Short description of this project
description: 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](#usage) section.
  
  ## Migration `v0` to `v1`
  
  There is an issue [The query contains `true` or `false` fails with an error](https://github.com/alexxander/jq-tools/issues/4).
  A workaround is to use a quote around `"true" and `"false" in a query.
  
  To migrate from `v0` to `v1`, quote in your queries all `true`/`false` and Github actions substitutions resovled to the values.
  
  ### Example
  
  * `query: .true` replace with `query: ."true"`
  * `query: .${{ inputs.from == '' }}` replace with `query: ."${{ inputs.from == '' }}"`  

references:
  - name: "github-actions-workflows"
    description: "Reusable workflows for different types of projects"
    url: "https://github.com/cloudposse/github-actions-workflows"
  - name: "example-github-action-release-workflow"
    description: "Example application with complicated release workflow"
    url: "https://github.com/cloudposse/example-github-action-release-workflow"

# How to use this project
usage: |-
  ### Define constants 
  ```yaml
    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: cloudposse/github-action-yaml-config-query@main
            with:
              config: |
                image: acme/example
                tag: sha-${{ github.sha }}
  
          - run: |
            docker run ${{ steps.context.outputs.image }}:${{ steps.context.outputs.tag }}
  ```

  ### Implement if/else
  ```yaml
    name: Promote
    on:
      workflow_call:
        inputs:
          from:
            required: false
            type: string

    jobs:
      demo:
        runs-on: ubuntu-latest
        steps:
          - name: Context
            id: from
            uses: cloudposse/github-action-yaml-config-query@main      
            with:
              query: ."${{ inputs.from == '' }}"
              config: |-
                true: 
                  tag: ${{ github.sha }}
                false:
                  tag: ${{ inputs.from }}
  
          - run: |
            docker tag acme/example:${{ steps.context.outputs.tag }}
  ```

  ### Implement switch
  ```yaml
    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: cloudposse/github-action-yaml-config-query@main      
            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 }}
  ```

include:
  - "docs/github-action.md"

# Contributors to this project
contributors:
  - name: "Igor Rodionov"
    github: "goruha"