LabHit Docs

Pipeline Reference

Complete reference for LabHit pipeline YAML format.

File Location

LabHit reads your pipeline from .labhit.yaml at your repository root -- the same file for both local runs and the webhook flow:

How you run File location
Locally with labhit run .labhit.yaml (or .labhit.yml) at your project root
GitHub / webhook flow .labhit.yaml (or .labhit.yml) at your repository root

labhit run resolves .labhit.yaml first, then .labhit.yml, falling back to .labhit/pipeline.yaml only when no root file exists. When LabHit receives a push webhook, it clones the repository and runs the same .labhit.yaml from the repo root. Everything in this reference applies to both.

Top-Level Fields

engine: "1"              # Required. Engine version (currently "1").

pipeline:
  name: my-pipeline      # Required. Pipeline identifier.
  description: "..."     # Optional. Human-readable description.

triggers:                # Optional. Event-based pipeline triggers.
  push: {}
  pull_request: {}
  manual: {}
  schedule: {}

stages:                  # Required. Pipeline stage definitions.
  stage-name:
    # ... stage fields

Stage Fields

Each stage supports these fields:

Field Type Description
use string Extension to invoke (category/name format)
run string Inline shell command (when no extension needed)
after list<string> Stage dependencies (builds a DAG)
with map<string, any> Configuration passed to the extension
sandbox object Execution environment configuration
gate object Policy gate (must pass before stage runs)
timeout integer Maximum stage runtime in seconds
retry object Retry policy (max_attempts, backoff)
condition string Expression controlling whether the stage runs

A stage must have either use or run, not both.

use -- Extension Invocation

stages:
  fetch:
    use: source/git        # category/name format
    with:
      depth: 1             # Extension-specific configuration
      submodules: true

Extensions follow the category/name naming convention:

Category Purpose Examples
source Source code retrieval source/git, source/s3
build Build and compilation build/container, build/cargo
test Test execution test/cargo, test/jest
scan Security scanning scan/trivy, scan/grype
deploy Deployment targets deploy/kubernetes, deploy/lambda
notify Notifications notify/slack, notify/email
gate Approval workflows gate/manual, gate/policy

run -- Inline Commands

stages:
  lint:
    after: [fetch]
    run: cargo clippy -- -D warnings
    sandbox:
      image: rust:1.93-slim

after -- Dependencies

stages:
  test:
    after: [fetch]         # Runs after fetch completes successfully

  deploy:
    after: [build, scan]   # Runs after both build AND scan succeed

Dependencies form a directed acyclic graph (DAG). The scheduler runs independent stages in parallel and respects dependency ordering. If a dependency fails, downstream stages are cancelled.

sandbox -- Execution Environment

stages:
  build:
    use: build/container
    sandbox:
      image: rust:1.93-slim    # Container image
      resources:
        cpu: 2                 # CPU cores
        memory: 4Gi            # Memory limit
        timeout: 600           # Timeout in seconds
      env:
        CARGO_HOME: /cache/cargo

gate -- Policy Gates

stages:
  deploy:
    use: deploy/kubernetes
    gate:
      approval: required       # Manual approval needed
      policy: production-deploy # Named policy must pass

Triggers

Push

triggers:
  push:
    branches: [main, "release/*"]

Only branches (glob patterns) is supported. Path filters (paths:) are not yet implemented.

Pull Request

triggers:
  pull_request:
    branches: [main]

Only branches (glob patterns) is supported. Event-type filters (types:) are not yet implemented.

Manual

triggers:
  manual: {}

Schedule (Cron)

triggers:
  schedule:
    cron: "0 2 * * *"    # Daily at 2 AM

Variable Interpolation

LabHit supports variable interpolation in stage configuration:

stages:
  build:
    use: build/container
    with:
      tags:
        - "${{ var.registry }}/app:${{ run.id }}"
        - "${{ var.registry }}/app:latest"

Available Contexts

Context Description Examples
var.* User-defined variables var.registry, var.environment
run.* Current run metadata run.id, run.name
stage.* Upstream stage outputs stage.build.output.image

Complete Example

engine: "1"

pipeline:
  name: build-and-deploy
  description: "Build, test, scan, and deploy"

triggers:
  push:
    branches: [main, "release/*"]
  pull_request:
    branches: [main]

stages:
  fetch:
    use: source/git
    with:
      depth: 1

  lint:
    after: [fetch]
    run: cargo clippy -- -D warnings
    sandbox:
      image: rust:1.93-slim

  test:
    after: [fetch]
    run: cargo test --workspace
    sandbox:
      image: rust:1.93-slim
      resources:
        cpu: 2
        memory: 4Gi

  build:
    after: [lint, test]
    use: build/container
    with:
      context: "."
      dockerfile: Dockerfile
      tags:
        - "${{ var.registry }}/app:${{ run.id }}"

  scan:
    after: [build]
    use: scan/trivy
    with:
      target: "${{ stage.build.output.image }}"
      fail_on: [critical, high]

  deploy:
    after: [build, scan]
    use: deploy/kubernetes
    with:
      manifests: ./k8s/
      namespace: "${{ var.environment }}"
    gate:
      approval: required
      policy: production-deploy