LabHit Docs

Pipeline Reference

Complete reference for LabHit pipeline YAML format.

File Location

The same YAML format is read from two locations, depending on how you run it:

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

When LabHit receives a push webhook, it clones the repository and runs the .labhit.yaml from the repo root. Everything in this reference applies to both locations.

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)

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/*"]
    paths:
      - "src/**"
      - "Cargo.toml"

Pull Request

triggers:
  pull_request:
    branches: [main]
    types: [opened, synchronize]

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.sha_short }}"
        - "${{ var.registry }}/app:latest"

Available Contexts

Context Description Examples
var.* User-defined variables var.registry, var.environment
run.* Current run metadata run.sha_short, run.branch, run.id
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.sha_short }}"

  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