
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 |
flow-binary |
Path to a pre-built flow binary to use instead of installing one (relative to the workspace root). Takes precedence over flow-version. |
|
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 }}
Testing an Unreleased flow Build
Set flow-binary to run your executables with a flow binary you just built, instead of an
installed release. This matters when the repository is flow, or when a task depends on a
flow feature that has not shipped yet — otherwise CI runs the released flow against the code
under review, and a task using the new behavior fails no matter what the PR does.
- name: Build flow
run: go build -o ./bin/flow .
- name: Run tests with the freshly built flow
uses: flowexec/action@v1
with:
executable: 'test unit'
flow-binary: ./bin/flow
The path is relative to the workspace root, and takes precedence over flow-version.
Requirements
- Valid flow workspaces and executables in your repository
- GitHub Actions runner (
ubuntu-latest, macos-latest, or windows-latest)