Skip to content

Quick Start

From zero to a running service in 5 minutes.

Prerequisites

  • Repository in GitLab (group infrastructure/hive/)
  • Service listens on HTTP on some port
  • Service has a health endpoint (can be just /)

Step 1: Create .hive.yml

Create a .hive.yml file in the root of your repository:

name: my-service
port: 8080

This is the minimal configuration. Hive will automatically detect the language and build a container.

Default name

If name is not specified, Hive will use the directory name or project name from the git remote.

Step 2: Set up CI

Create .gitlab-ci.yml in the repository root:

stages:
  - generate
  - run

generate-pipeline:
  stage: generate
  image: lab.xmonetize.net:5050/infrastructure/hive/hive-api/cli:latest
  script:
    - hive ci --global > child-pipeline.yml
  artifacts:
    paths:
      - child-pipeline.yml

run-pipeline:
  stage: run
  trigger:
    include:
      - artifact: child-pipeline.yml
        job: generate-pipeline
    strategy: depend

This automatically generates a full CI pipeline from your .hive.yml files.

Step 3: Push

git add .hive.yml .gitlab-ci.yml
git commit -m "Add Hive configuration"
git push

The pipeline will start automatically:

  1. init — registers the repository in ArgoCD
  2. build — builds a container using Cloud Native Buildpacks (or Dockerfile)
  3. test — starts the container and checks the health endpoint
  4. deploy — deploys via ArgoCD to Kubernetes

Step 4: Get your URL

After a successful deploy, the service will be available at:

Environment URL
Staging https://{name}.{namespace}.knative-staging.svcik.org
Production https://{name}.{namespace}.knative.svcik.org

For example: https://my-service.hive-examples.knative-staging.svcik.org

Examples

See ready-made examples in the hive-examples repository:

# helloworld-go/.hive.yml
name: helloworld-go
port: 8080

// main.go
package main

import (
    "fmt"
    "net/http"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello World from Go!")
    })
    http.ListenAndServe(":8080", nil)
}

# helloworld-python/.hive.yml
name: helloworld-python
port: 8080

# app.py
from http.server import HTTPServer, BaseHTTPRequestHandler

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b"Hello World from Python!")

HTTPServer(("", 8080), Handler).serve_forever()

# helloworld-dotnet/.hive.yml
name: helloworld-dotnet
port: 8080

// Program.cs
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World from .NET!");
app.Run("http://0.0.0.0:8080");

Claude Code integration

Add the Hive skill so Claude Code can help with configuration, CI setup, and troubleshooting.

Global (all projects on your machine):

git clone git@lab.xmonetize.net:infrastructure/hive/hive-skills.git ~/.claude/skills/hive

Per-project (shared with team via git):

git submodule add git@lab.xmonetize.net:infrastructure/hive/hive-skills.git .claude/skills/hive
git commit -m "Add hive skill for Claude Code"

To update: cd ~/.claude/skills/hive && git pull (global) or git submodule update --remote .claude/skills/hive (per-project).

Before working with Hive

Always start with /hive in Claude Code. This loads the latest skill context and checks for updates. Make it a habit — like git pull before starting work.

What's next