AkurAI-Build

public

Latest change 32946d79ecd7d436b3978f5757db6b3a392b3ca8 - AKURAI-BUILD-11 consolidate self-hosted deployment by Ólafur Búi Ólafsson

---
name: akurai-build
description: Operates the Titan-hosted AkurAI Build Git and CI/CD system through hosted Git plus MCP repository, run, artifact, promotion, and verification tools.
compatibility: Requires SSH alias titan; production is reached through the AkurAI-VPN mesh.
license: MIT
---

# AkurAI Build operations

Read `../../../deploy.md` before every task. Check this skill before running anything. Repository, pipeline, run, artifact, and promotion operations go through the `akurai-build` MCP tool set, not shell commands. Direct shell/SSH/system commands are read-only probes only; after a successful probe, add the operation and a focused check to the MCP tool set and update this skill before reusing it.

Canonical source is `~/Projects/AkurAI-Build` on Titan. Production is `https://akurai-build.olibuijr.com`; EC2 Nginx proxies through AkurAI-VPN to Titan `100.88.0.9:3210`.

Deploy through AkurAI Build's hosted Git and MCP-controlled CI/CD:

1. Run the repository's focused local checks.
2. Commit only the intended paths in the trusted Titan checkout and record the full commit SHA.
3. Publish that immutable revision with `mcp__akurai_build_akurai_repo_sync`.
4. Confirm the hosted branch head with `mcp__akurai_build_akurai_repo_branches`.
5. Queue the exact SHA with `mcp__akurai_build_akurai_run_queue`.
6. Inspect or wait through `akurai_run_show`/`akurai_run_wait`; if the run persists as `waiting`, promote the named protected environment with `akurai_run_promote`.
7. Require persisted `succeeded` state, then verify public health and the changed behavior.

Never invoke `akurai-ec2 release`, `deploy.sh publish|release|deploy`, raw Git push, direct Build HTTP, or manual service/filesystem mutations as an agent-side deployment path. Operator commands may run inside a committed `.akurai.yml` job after the run is queued through MCP.

## MCP tool set

Use the configured `mcp__akurai_build_akurai_<name>` tools directly. Never invoke the installed binary's stdio protocol, direct HTTP, or `deploy.sh cli|mcp` as a substitute. The mounted tool schema is authoritative; the current deployment tool set is:

```
akurai_doctor controller diagnostics: database readiness, git, docker
akurai_repo_list query repositories by text/visibility
akurai_repo_add register an external repository by URL
akurai_repo_host mirror + host from a trusted Titan checkout
akurai_repo_sync sync a hosted mirror from its trusted checkout
akurai_repo_rename rename a registered repository
akurai_repo_remove unregister + delete mirror; cascades runs/artifacts (destructive)
akurai_repo_visibility set private/public dashboard visibility
akurai_repo_branches list remote branch heads via git ls-remote
akurai_repo_tree browse a repository's file tree at a ref/sub-path
akurai_init write a minimal .akurai.yml template to a path
akurai_release bump version + cut changelog + commit/tag in the trusted checkout, sync mirror, queue the release run — the single release path for every product
akurai_run_queue queue a pipeline run, optionally waiting
akurai_runs query runs across repositories with filters
akurai_run_show read one run: jobs, artifacts, deployments
akurai_run_wait poll a run until terminal/approval-required
akurai_run_logs job logs for a run, optionally failed-only
akurai_run_retry queue the same immutable revision as a prior run
akurai_run_promote approve/resume a protected environment (production-impacting)
akurai_artifact_get copy a build artifact to a Titan path
akurai_workers Titan worker status, capacity, heartbeat
```

Every tool returns its JSON payload as the sole `content` text entry, or `isError: true` with a message; MCP never exposes protected secrets. Require persisted `status == "succeeded"` before claiming a build or deployment succeeded; `waiting` requires an explicit `akurai_run_promote`, and `queued`/`running` are incomplete. `akurai_runs`' `repo`/`status`/`trigger` filters accept a string, comma-separated values, or an array. `akurai_repo_remove` and `akurai_run_promote` are consequential — confirm intent before calling them.

`akurai_repo_host` is the only supported migration from an external remote into AkurAI Build Git: it creates a complete bare mirror below the protected data root, enables authenticated Smart HTTP writes, and updates the CI registration only after the mirror succeeds. `akurai_repo_sync` publishes later changes from the trusted Titan checkout. The clone URL is `https://akurai-build.olibuijr.com/git/<name>.git`; Smart HTTP requires the protected API bearer token through a credential helper or maintained command — never place it in a URL, command argument, source file, Markdown, or logs.

`akurai_repo_remove` unregisters a repository and deletes its hosted bare mirror
(`~/.local/share/akurai-build/hosted/<name>.git`), cascading to that repository's runs,
jobs, logs, and artifacts. It is destructive and irreversible; confirm the name first with
`akurai_repo_list`. Repositories registered by URL (no local mirror) are unregistered without a
mirror deletion.

## Source lifecycle

The trusted Titan checkout is the editing source. AkurAI Build hosted Git is the publication source, and the queued immutable commit is the deployment source:

```text
local checks → local commit → repo_sync → verify branch head → run_queue(commit) → wait/promote → persisted success → acceptance
```

Do not deploy a moving branch or dirty workspace. Do not report `queued`, `running`, `waiting`, or a successful package job as deployed.

AkurAI Build is self-hosted and since 2026-07-16 runs as TWO docker containers on Titan: `akurai-build-service` (serve-only, `AKURAI_WORKERS=0`, public 0.0.0.0:3210, mem 1g/2cpu) and `akurai-build-worker` (`AKURAI_WORKERS=1`, loopback :3211, mem 8g/8cpu, docker.sock + host tool mounts). Runs execute ONLY in the worker container, so native cargo builds inherit the worker cgroup. The self-pipeline's protected `deploy-production` job consumes the package job's prebuilt binary and atomically replaces only the service container through `deploy/service-deploy.sh`; it verifies both endpoints and rolls the service back if health fails. The service restart may briefly interrupt the MCP-visible controller while the worker persists the result; inspect the existing run rather than re-queueing after a timeout. Explicit service+worker and host-MCP maintenance uses `deploy/compose-release.sh` outside the worker so it cannot self-sever.

If the installed MCP server lacks a required capability, update the MCP contract and deploy it through an already-supported pipeline path. Never use raw stdio, direct HTTP, or an installed-file edit to bypass an older server.

## IDP / OIDC setup

AkurAI Build authenticates through the AkurAI IDP at `auth.olibuijr.com`.
Provision the OIDC client once through the maintained EC2 CLI:

```sh
~/.local/bin/akurai-ec2 provision-oidc-client "AkurAI Build" \
https://akurai-build.olibuijr.com/auth/callback \
--scopes "openid profile email groups" \
--grant-types "authorization_code refresh_token" \
--first-party
```

This writes `AKURAI_BUILD_IDP_CLIENT_ID`, `AKURAI_BUILD_IDP_CLIENT_SECRET`,
and related vars to `~/.config/akurai-build/env` (mode 0600). The service
reads them at startup via the `IdpConfig::from_env` path in `src/auth.rs`.

Required env vars (set by provisioning):
- `AKURAI_BUILD_IDP_ISSUER` (default `https://auth.olibuijr.com`)
- `AKURAI_BUILD_IDP_CLIENT_ID`
- `AKURAI_BUILD_IDP_CLIENT_SECRET`
- `AKURAI_BUILD_IDP_REDIRECT`
- `AKURAI_BUILD_ADMIN_EMAILS` (comma-separated list of admin email addresses)

The provision script at `scripts/provision-oidc-client.sh` is a legacy
standalone copy; prefer the `akurai-ec2 provision-oidc-client` CLI command.
Secrets belong only in protected files under `~/.config/akurai-build/` or as `AKURAI_SECRET_<NAME>` entries in its mode-0600 environment file. Never retrieve, echo, log, pass, or store their values in commands, Markdown, Git, or SQLite. Native jobs require a trusted repository and an explicit production opt-in; prefer restricted Docker jobs.