LabHit Docs

Getting Started

LabHit is a modular CI/CD engine that runs inside the tools you already use. Add it to your existing CI, run it across any cloud, or run it standalone as a single binary. Same engine, same pipeline vocabulary. This guide takes you from zero to a running pipeline in under five minutes.

One config file, one vocabulary. LabHit reads .labhit.yaml from your repository root -- both locally with labhit run and through the GitHub/webhook flow. On each push, LabHit clones the repo and runs that same file. The YAML format is identical everywhere.

Prefer to look before you install? Try the hosted beta at app.labhit.dev.

Prerequisites

  • macOS (Apple Silicon or Intel) or Linux (x86_64)
  • Docker (optional: only needed for sandboxed container stages)

Install LabHit

Quick install

curl -sSf https://api.labhit.dev/install | sh

This downloads the labhit binary for your platform. Add it to your PATH:

export PATH="$HOME/.labhit/bin:$PATH"

Build from source

Requires Rust 1.75+ and the wasm32-wasip1 target:

git clone https://github.com/Lab-Hit/labhit.git
cd labhit
cargo build --release

Binary: target/release/labhit

Create a project

mkdir my-project && cd my-project
labhit init

This creates a .labhit.yaml pipeline definition at your project root (and an optional .labhit/config.yaml for local settings).

Write your first pipeline

Edit .labhit.yaml:

engine: "1"

pipeline:
  name: hello-world
  description: "My first LabHit pipeline"

stages:
  greet:
    run: echo "Hello from LabHit!"

  check:
    after: [greet]
    run: echo "Pipeline is working."

Two stages. check depends on greet via after:. The scheduler runs them in order.

Run it

labhit run

Output:

▶ Running pipeline: hello-world
  ✓ greet (0.1s)
  ✓ check (0.1s)
✓ Pipeline succeeded (2/2 passed)

Validate without running

Check your pipeline YAML for syntax errors and dependency cycles:

labhit validate

Run it inside your CI

LabHit doesn't have to replace your current CI. It can run inside it. The path that works today is the webhook receiver:

  1. Run a LabHit server (labhit serve) reachable from your Git host.
  2. Commit a .labhit.yaml to your repository root.
  3. Point the repository's push webhook at https://your-server.example.com/webhook.

On every push, LabHit clones the repository, reads .labhit.yaml, and runs the pipeline (isolated and policy-checked) alongside whatever CI you already use. See Webhook Integration for the full setup.

A dedicated GitHub App experience (commit status checks, a connect-your-repo flow, and per-repo secrets) is on the roadmap.

Add a container stage

With Docker installed, stages can run inside containers:

engine: "1"

pipeline:
  name: containerized-build
  description: "Run inside Docker containers"

stages:
  setup:
    run: echo "Preparing workspace"

  build:
    after: [setup]
    run: rustc --version && echo "Rust toolchain available"
    sandbox:
      image: rust:1.93-slim
      resources:
        cpu: 2
        memory: 4Gi
        timeout: 300

LabHit detects Docker automatically and routes sandbox: stages to containers. Stages without sandbox: run as local processes.

Use an extension

Extensions are WASM modules that handle specialized tasks. Use them with the use: keyword:

engine: "1"

pipeline:
  name: build-with-extensions
  description: "Pipeline using extensions"

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

Extensions follow the category/name naming convention (e.g., source/git, build/container, scan/trivy).

Install extensions from the registry:

labhit extension install source/git

Or build your own, see the Extension Guide.

Add a policy gate

Gates enforce policies before a stage can run:

stages:
  deploy:
    after: [build, scan]
    use: deploy/kubernetes
    gate:
      approval: required
      policy: production-deploy

If the gate fails, the stage is marked as Failed and downstream stages are cancelled.

Variable interpolation

Reference variables, run context, and upstream stage outputs:

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

  deploy:
    after: [build]
    use: deploy/kubernetes
    with:
      image: "${{ stage.build.output.image }}"

Available contexts:

Context Description
var.* User-defined variables
run.* Current run metadata (id, name)
stage.* Upstream stage outputs (stage.<name>.output.<key>)
env.* Disabled for security -- interpolation always resolves to empty

Authenticate (optional)

For cloud features (usage tracking, extension registry, dashboard), authenticate with GitHub:

labhit auth login

CLI login is rolling out. The command-line device flow isn't enabled against api.labhit.dev yet -- for now, sign in through the web dashboard at app.labhit.dev.

When enabled, this opens your browser for GitHub authorization and stores your credentials securely at ~/.labhit/credentials.json.

Check your status:

labhit auth status

Next steps