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.

Two config paths, one vocabulary. Locally, labhit run uses .labhit/pipeline.yaml in your project. For the GitHub/webhook flow, commit a .labhit.yaml to your repository root — on each push, LabHit clones the repo and runs that file. The YAML format is identical; only the entry point differs.

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/ directory with a starter pipeline definition.

Write your first pipeline

Edit .labhit/pipeline.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.sha_short }}"

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

Available contexts:

Context Description
var.* User-defined variables
run.* Current run metadata (sha_short, branch, id)
stage.* Upstream stage outputs (stage.<name>.output.<key>)
env.* Environment variables

Authenticate (optional)

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

labhit auth login

This opens your browser for GitHub authorization. Once complete, your credentials are stored securely at ~/.labhit/credentials.json.

Check your status:

labhit auth status

Next steps