action.yaml

name: 'Flow Execute'
description: 'Execute flow workflows in GitHub Actions'
author: 'jahvon'

inputs:
  executable:
    description: 'Flow executable to run (e.g., "VERB NAME", "build app", "test unit", "deploy staging")'
    required: true

  workspace:
    description: 'Flow workspace to use (path or name)'
    required: false
    default: '.'

  workspace-name:
    description: 'Name for the workspace (auto-generated if not provided)'
    required: false
    default: ''

  workspaces:
    description: 'YAML/JSON map of workspaces (supports local paths and git repositories)'
    required: false
    default: ''

  clone-token:
    description: 'GitHub token for cloning private repositories'
    required: false
    default: ''

  clone-depth:
    description: 'Git clone depth for repository cloning (0 for full history)'
    required: false
    default: '1'

  flow-version:
    description: 'Version of flow CLI to install'
    required: false
    default: 'latest'

  params:
    description: 'Parameters to pass to the executable (KEY=VALUE pairs, one per line or comma-separated)'
    required: false
    default: ''

  env:
    description: 'Environment variables to set during execution (KEY=VALUE pairs, one per line)'
    required: false
    default: ''

  secrets:
    description: 'Secrets to set in flow vault (KEY=VALUE pairs, one per line; JSON object also accepted)'
    required: false
    default: ''

  vault-key:
    description: 'Vault encryption key (for existing vaults)'
    required: false

  working-directory:
    description: 'Directory to run flow from'
    required: false
    default: '.'

  timeout:
    description: 'Timeout for executable execution'
    required: false
    default: '30m'

  upload:
    description: 'Upload flow logs as an artifact'
    required: false
    default: 'false'

  continue-on-error:
    description: 'Continue workflow if flow executable fails'
    required: false
    default: 'false'

outputs:
  exit-code:
    description: 'Exit code of the flow executable'
    value: ${{ steps.flow-exec.outputs.exit-code }}

  output:
    description: 'Output from the flow executable'
    value: ${{ steps.flow-exec.outputs.output }}

  vault-key:
    description: 'Generated vault encryption key (when secrets are configured without a provided key)'
    value: ${{ steps.flow-vault.outputs.vault-key }}

  error-code:
    description: 'Machine-readable error code from flow (e.g., EXECUTION_FAILED, TIMEOUT, NOT_FOUND)'
    value: ${{ steps.flow-exec.outputs.error-code }}

runs:
  using: 'composite'
  steps:
    - name: Resolve flow install path
      shell: bash
      id: flow-paths
      run: |
        case "$(uname -s)" in
          MINGW*|MSYS*|CYGWIN*) echo "install-dir=$(cygpath -w "$HOME/bin")" >> "$GITHUB_OUTPUT" ;;
          *)                     echo "install-dir=/usr/local/bin" >> "$GITHUB_OUTPUT" ;;
        esac

        version="${FLOW_VERSION:-latest}"
        if [ "$version" = "main" ]; then
          echo "cache-key=flow-main-${{ runner.os }}-${{ runner.arch }}-$(date +%Y%m%d)" >> "$GITHUB_OUTPUT"
        else
          echo "cache-key=flow-${version}-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_OUTPUT"
        fi
      env:
        FLOW_VERSION: ${{ inputs.flow-version }}

    - name: Cache flow binary
      uses: actions/cache@v4
      id: flow-cache
      with:
        path: ${{ steps.flow-paths.outputs.install-dir }}/flow*
        key: ${{ steps.flow-paths.outputs.cache-key }}

    - name: Install flow CLI
      shell: bash
      run: |
        # Install flow CLI
        source "$SCRIPTS_DIR/install-flow.sh"
      env:
        SCRIPTS_DIR: ${{ github.action_path }}/scripts
        FLOW_VERSION: ${{ inputs.flow-version }}
        TIMEOUT: ${{ inputs.timeout }}
        CACHE_HIT: ${{ steps.flow-cache.outputs.cache-hit }}

    - name: Setup flow workspaces
      shell: bash
      run: |
        # Setup flow workspaces
        source "$SCRIPTS_DIR/setup-workspaces.sh"
      working-directory: ${{ inputs.working-directory }}
      env:
        SCRIPTS_DIR: ${{ github.action_path }}/scripts
        WORKSPACES_INPUT: ${{ inputs.workspaces }}
        WORKSPACE_PATH: ${{ inputs.workspace }}
        WORKSPACE_NAME: ${{ inputs.workspace-name }}
        CLONE_TOKEN: ${{ inputs.clone-token }}
        CLONE_DEPTH: ${{ inputs.clone-depth }}
        EXECUTABLE_INPUT: ${{ inputs.executable }}

    - name: Setup vault and secrets
      shell: bash
      run: |
        # Setup vault and secrets
        source "$SCRIPTS_DIR/setup-vault.sh"
      working-directory: ${{ inputs.working-directory }}
      id: flow-vault
      if: inputs.secrets != '' || inputs.vault-key != ''
      env:
        SCRIPTS_DIR: ${{ github.action_path }}/scripts
        SECRETS_INPUT: ${{ inputs.secrets }}
        VAULT_KEY: ${{ inputs.vault-key }}

    - name: Execute flow executable
      shell: bash
      run: |
        # Execute: flow ${{ inputs.executable }}
        source "$SCRIPTS_DIR/execute.sh"
      working-directory: ${{ inputs.working-directory }}
      id: flow-exec
      env:
        SCRIPTS_DIR: ${{ github.action_path }}/scripts
        EXECUTABLE_INPUT: ${{ inputs.executable }}
        PARAMS_INPUT: ${{ inputs.params }}
        ENV_INPUT: ${{ inputs.env }}
        VAULT_KEY: ${{ inputs.vault-key }}
        CONTINUE_ON_ERROR: ${{ inputs.continue-on-error }}
        CAPTURE: ${{ inputs.upload == 'true' }}

    - name: Upload flow logs
      uses: actions/upload-artifact@v4
      if: ${{ inputs.upload == 'true' && steps.flow-exec.outputs.exit-code != '0' }}
      with:
        name: flow-executable-logs-${{ github.job }}
        path: ${{ inputs.working-directory }}/executable_output.txt
        retention-days: 1

branding:
  icon: 'play'
  color: 'white'