Skip to main content

Your first pipeline

This walkthrough takes a typical Node.js repo from "no CI" to "every push runs npm test and pushes a tagged Docker image" in about ten minutes.

Prerequisites​

  • A workspace on Loha (sign up if you don't have one)
  • A GitLab repository connected to that workspace
  • Local git and a working repo

There are four steps, and the third one is the one people skip.

1. Connect your repository​

In the Loha dashboard, open your workspace → Repositories → Connect repository. Pick the Git host, provide an access token, and select the repo.

If your workspace has more than one project, you'll be asked which one the repo belongs to. For supported hosts and exact token scopes, see Repositories & Git hosts.

2. Add a .loha.yml to your repo​

Create .loha.yml at the root of your repo:

version: '1'
name: nodejs-build-and-publish

on:
  push:
    branches: [main]

jobs:
  test:
    resource_class: small
    steps:
      - name: Checkout
        uses: loha/git-clone@v1
      - name: Install
        run: npm ci
      - name: Test
        run: npm test

  publish:
    needs: [test]
    resource_class: medium
    steps:
      - name: Checkout
        uses: loha/git-clone@v1
      - name: Build and push
        uses: loha/buildah-build@v1
        with:
          IMAGE: registry.example.com/acme/web:${COMMIT_SHA}

Commit and push.

IMAGE carries the whole image reference, tag included. ${COMMIT_SHA} is one of three context tokens Loha substitutes into with: values. Each task defines its own parameters, and a with: key the task doesn't declare is silently ignored, so check the catalog page for any task you add.

Prefer to write it with an AI agent?

This is the step an agent helps with most, because validate_pipeline runs Loha's real parser (the same one the platform uses at build time), so "valid in your editor" means "valid in the cluster":

  • "Write a .loha.yml for this repo, then validate it against Loha's schema and fix anything it flags."
  • "Check my .loha.yml's uses: steps against Loha's step catalog: are all the with: parameters real?"

That second prompt matters: validation catches schema errors and unknown task names, but not a wrong with: key. Those fail (or silently do nothing) only once a build runs.

Connect in two minutes · Claude Code & Cursor

3. Create a trigger​

A trigger is what listens for the push and starts a build.

If your repository already had a .loha.yml when you connected it, you have one already. Loha reads the file at connect time, creates a trigger from its on: block, and registers the webhook. Check the repository page: it says either "Building on every push to main" or why it is not.

Only if that is missing do you create one by hand: go to Triggers → New trigger, choose the Repository mode, pick your repo, tick the push event, and filter to main.

Loha adds the webhook to your Git host for you, provided the token on your repo host is allowed to manage webhooks. If it isn't, you get the URL and secret to paste in yourself, a one-time step per trigger. Either way the next push to main starts a build. Full walkthrough, including the per-host secret field: Creating a trigger.

4. Watch it run​

Push a commit. The webhook fires within a second and the dashboard shows a new build under Builds. Click in: logs stream live, and each step lands as it finishes.

Nothing appeared? Check your Git host's webhook delivery log: a 401 means the secret doesn't match, a 404 means the URL is wrong.

Prefer the terminal?

The same connect → run → watch loop will be available from the Loha CLI (loha deploy, loha builds), coming soon. The API it runs on is live today.

Prefer to ask an agent?

With the MCP server connected, you can check the result without switching windows:

  • "Did my last push's build finish? If it failed, show me the failing step and its logs."

Using AI with Loha · Data sovereignty

What just happened​

  • Your Git host delivered a webhook to the trigger you created, which matched its push event and main branch filter.
  • Loha parsed your .loha.yml against the v1 schema.
  • The test and publish jobs ran as a build inside your workspace's isolated environment.
  • loha/git-clone@v1 and loha/buildah-build@v1 are official tasks: pinned, signed, and version-locked.
  • registry.example.com stands in for your registry: Loha pushes to a registry you bring, not one it hosts for you. Add its credentials under Settings → Registries before the publish job can push.
  • The publish job won't run until test passes: that's needs: [test].

What to try next​

When things go wrong​

The parser returns specific error messages with line numbers. Cross-reference them against the .loha.yml errors reference.

If the build runs but the step fails, the logs show the exit code and last 200 lines of stderr: click the failing step in the dashboard.