Execute flow workflows in your GitHub Actions.

Quick Start

- uses: flowexec/action@v1
  with:
    executable: 'build app'

Check out the flow CI workflow for examples of how this can be used.

Inputs

Required

• executable - flow executable ID (VERB NAME) to run (e.g., "validate", "build app", "test unit", "deploy staging")

Optional

Input	Description	Default
workspace	Workspace to use (path or name)	.
workspace-name	Name for the workspace (auto-generated if not provided)
workspaces	YAML/JSON map of workspaces (supports local paths and git repositories)
clone-token	GitHub token for cloning private repositories
clone-depth	Git clone depth for repository cloning (0 for full history)	1
flow-version	Version of flow CLI to install	latest
params	Parameters to pass to the executable (KEY=VALUE pairs, one per line or comma-separated)
env	Environment variables to set during execution (KEY=VALUE pairs, one per line)
secrets	Secrets to set in flow vault (KEY=VALUE pairs, one per line; JSON also accepted)
vault-key	Vault encryption key (for existing vaults)
working-directory	Directory to run flow from	.
timeout	Timeout for executable execution	30m
continue-on-error	Continue workflow if flow executable fails	false
upload	Upload flow logs as an artifact on failure	false

Outputs

Output	Description
exit-code	Exit code of the flow executable
output	Captured output from the flow executable (when upload: true)
vault-key	Generated vault encryption key (when secrets are configured without a provided key)
error-code	Machine-readable error code on failure (e.g., EXECUTION_FAILED, TIMEOUT, NOT_FOUND)

Examples

Basic Usage

name: Build and Test
on: [push, pull_request]

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

      - name: Build application
        uses: flowexec/action@v1
        with:
          executable: 'build app'

      - name: Run tests
        uses: flowexec/action@v1
        with:
          executable: 'test unit'

Passing Parameters

- name: Run tests with CI mode
  uses: flowexec/action@v1
  with:
    executable: 'test unit'
    params: |
      CI=true
      COVERAGE=true

Parameters are passed as --param KEY=VALUE flags to the flow executable. You can also use comma-separated format:

    params: 'CI=true, COVERAGE=true'

Environment Variables

- name: Publish release
  uses: flowexec/action@v1
  with:
    executable: 'publish release'
    params: 'VERSION=1.2.0'
    env: |
      GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN=${{ secrets.NPM_TOKEN }}

Multi-Workspace (Local + Remote)

Git repositories are cloned and registered as workspaces automatically by flow. Use clone-token for private repos.

- name: Deploy to staging
  uses: flowexec/action@v1
  with:
    executable: 'deploy staging'
    workspaces: |
      backend: ./backend
      frontend: https://github.com/user/frontend-repo.git
      shared: https://github.com/user/shared-lib.git
    clone-token: ${{ secrets.GITHUB_TOKEN }}

You can pin a specific branch or tag for git workspaces:

    workspaces: |
      app: .
      shared:
        repo: https://github.com/myorg/shared-flows.git
        ref: main
      stable:
        repo: https://github.com/myorg/releases.git
        ref: v1.0.0

With Secrets

- name: Deploy with secrets
  uses: flowexec/action@v1
  with:
    executable: 'deploy production'
    secrets: |
      DATABASE_URL=${{ secrets.DATABASE_URL }}
      API_KEY=${{ secrets.API_KEY }}

Cross-Job Vault Sharing

jobs:
  setup:
    outputs:
      vault-key: ${{ steps.init.outputs.vault-key }}
    steps:
      - uses: flowexec/action@v1
        id: init
        with:
          executable: 'validate'
          secrets: |
            SHARED_SECRET=${{ secrets.SHARED_SECRET }}

  deploy:
    needs: setup
    steps:
      - uses: flowexec/action@v1
        with:
          executable: 'deploy production'
          vault-key: ${{ needs.setup.outputs.vault-key }}
          secrets: |
            DEPLOY_KEY=${{ secrets.DEPLOY_KEY }}

Error Handling

Use continue-on-error with the error-code output to handle failures programmatically:

- name: Run migration
  uses: flowexec/action@v1
  id: migrate
  with:
    executable: 'migrate database'
    continue-on-error: 'true'

- name: Handle failure
  if: steps.migrate.outputs.exit-code != '0'
  run: |
    echo "Migration failed with error: ${{ steps.migrate.outputs.error-code }}"
    if [ "${{ steps.migrate.outputs.error-code }}" = "TIMEOUT" ]; then
      echo "Consider increasing the timeout"
    fi

Advanced Configuration

- name: Complex deployment
  uses: flowexec/action@v1
  with:
    executable: 'deploy staging'
    workspaces: |
      app: .
      terraform:
        repo: https://github.com/myorg/terraform.git
        ref: v1.2.0
      k8s:
        repo: https://github.com/myorg/k8s-configs.git
        ref: staging
    clone-token: ${{ secrets.GITHUB_TOKEN }}
    params: 'ENVIRONMENT=staging, DRY_RUN=false'
    env: |
      AWS_REGION=us-east-1
    timeout: '20m'
    secrets: |
      AWS_ACCESS_KEY=${{ secrets.AWS_ACCESS_KEY }}
      KUBECONFIG=${{ secrets.KUBECONFIG }}

Requirements

• Valid flow workspaces and executables in your repository
• GitHub Actions runner (ubuntu-latest, macos-latest, or windows-latest)