GitHub Action

The LumenFlow Gates GitHub Action runs your quality gates in CI/CD pipelines. It reads your gate configuration from workspace.yaml and executes the appropriate checks.

The maintained action lives in the LumenFlow monorepo at hellmai/lumenflow/actions/lumenflow-gates@v4. Do not use the old standalone action repository reference.

Quick Start

1. Add configuration (if not already present)

   # workspace.yaml
   version: '2.0'
   
   gates:
     execution:
       format: 'pnpm format:check'
       lint: 'pnpm lint'
       typecheck: 'pnpm typecheck'
       test: 'pnpm test'

2. Add the workflow

   # .github/workflows/gates.yml
   name: LumenFlow Gates
   
   on:
     pull_request:
       branches: [main]
     push:
       branches: [main]
   
   jobs:
     gates:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: hellmai/lumenflow/actions/lumenflow-gates@v4
           with:
             token: ${{ secrets.LUMENFLOW_TOKEN }}

3. Get your token

   Request a LUMENFLOW_TOKEN from licensing@lumenflow.dev and add it to your repository secrets.

Inputs

| Input | Description | Required | Default | | ------------------- | -------------------------------------- | -------- | ------- | | token | LumenFlow API token for usage tracking | Yes | - | | working-directory | Directory to run commands in | No | . | | skip-format | Skip format check | No | false | | skip-lint | Skip lint check | No | false | | skip-typecheck | Skip type check | No | false | | skip-test | Skip tests | No | false |

Outputs

| Output | Description | | ----------------- | ----------------------------------------- | | preset-detected | The preset or config mode that was used | | gates-passed | Whether all gates passed (true/false) |

Using Presets

For common languages, specify a preset instead of individual commands:

gates:
  execution:
    preset: 'node' # or 'python', 'go', 'rust', 'dotnet'

Preset Defaults

| Preset | Format | Lint | Typecheck | Test | | -------- | ----------------------------------- | ---------------------------------------- | -------------- | --------------- | | node | prettier --check . | eslint . | tsc --noEmit | npm test | | python | ruff format --check . | ruff check . | mypy . | pytest | | go | test -z "$(gofmt -l .)" | golangci-lint run | go vet ./... | go test ./... | | rust | cargo fmt --check | cargo clippy -- -D warnings | cargo check | cargo test | | dotnet | dotnet format --verify-no-changes | dotnet build --no-restore -warnaserror | - | dotnet test |

Overriding Preset Commands

You can use a preset and override specific commands:

gates:
  execution:
    preset: 'python'
    # Override just the lint command
    lint: 'mypy . && ruff check . && pylint src/'

Command Options

Commands can be strings or objects with additional options:

gates:
  execution:
    format: 'pnpm format:check'
    test:
      command: 'pnpm test -- --coverage'
      timeout: 300000 # 5 minutes
      continueOnError: false

Full Workflow Examples

Node.js with pnpm

name: LumenFlow Gates

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Run LumenFlow Gates
        uses: hellmai/lumenflow/actions/lumenflow-gates@v4
        with:
          token: ${{ secrets.LUMENFLOW_TOKEN }}

Python with Poetry

name: LumenFlow Gates

on:
  pull_request:
    branches: [main]

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

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install Poetry
        run: pip install poetry

      - name: Install dependencies
        run: poetry install

      - name: Run LumenFlow Gates
        uses: hellmai/lumenflow/actions/lumenflow-gates@v4
        with:
          token: ${{ secrets.LUMENFLOW_TOKEN }}

.NET

name: LumenFlow Gates

on:
  pull_request:
    branches: [main]

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

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Restore dependencies
        run: dotnet restore

      - name: Run LumenFlow Gates
        uses: hellmai/lumenflow/actions/lumenflow-gates@v4
        with:
          token: ${{ secrets.LUMENFLOW_TOKEN }}

Monorepo Support

Run gates on specific packages in a monorepo:

jobs:
  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hellmai/lumenflow/actions/lumenflow-gates@v4
        with:
          token: ${{ secrets.LUMENFLOW_TOKEN }}
          working-directory: packages/frontend

  backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hellmai/lumenflow/actions/lumenflow-gates@v4
        with:
          token: ${{ secrets.LUMENFLOW_TOKEN }}
          working-directory: packages/backend

Tip

Each package can have its own workspace.yaml with different gate commands, or you can use a shared config at the repo root.

Skipping Gates

Skip specific gates when needed:

- uses: hellmai/lumenflow/actions/lumenflow-gates@v4
  with:
    token: ${{ secrets.LUMENFLOW_TOKEN }}
    skip-test: 'true' # Skip tests for docs-only changes

Or conditionally based on changed files:

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

      - name: Check for code changes
        id: changes
        uses: dorny/paths-filter@v3
        with:
          filters: |
            code:
              - 'src/**'
              - 'packages/**'

      - uses: hellmai/lumenflow/actions/lumenflow-gates@v4
        with:
          token: ${{ secrets.LUMENFLOW_TOKEN }}
          skip-test: ${{ steps.changes.outputs.code != 'true' }}

Auto-Detection Fallback

If no gates.execution config is present, the action auto-detects your project type based on files:

| File | Detected Language | | ---------------- | ----------------- | | package.json | Node.js | | pyproject.toml | Python | | go.mod | Go | | Cargo.toml | Rust | | *.csproj | .NET |

Troubleshooting

Gate fails but works locally

Ensure your CI environment matches local:

• Same Node/Python/Go version
• Same package manager (pnpm vs npm)
• Dependencies installed before gates run

Token issues

1. Verify LUMENFLOW_TOKEN is set in repository secrets
2. Check the token is valid at lumenflow.dev/settings
3. Ensure the token has access to the repository

Timeout errors

Increase the timeout for slow commands:

gates:
  execution:
    test:
      command: 'pnpm test'
      timeout: 600000 # 10 minutes

Next Steps

• Gates Concepts - Understanding gates
• Configuration Reference - Full config schema
• CLI Reference - Running gates locally