AkurAI Build
Sign in with AkurAI ID
Menu

AkurAI-Build

public

Latest change d9261b00163d0d35c15f9f161ad9c8b89b9688d7 - Document push-triggered CI, single-service deploy agent, and git push workflow 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; laptop clones of hosted Git are equally valid editing sources. 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 and `git push` to hosted Git
   (`https://akurai-build.olibuijr.com/git/<name>.git`, bearer token via a
   protected `http.<url>.extraHeader`). The push queues a webhook run
   automatically when the repository carries `.akurai.yml`. Trusted Titan
   checkouts may alternatively publish with
   `mcp__akurai_build_akurai_repo_sync` + `akurai_run_queue`.
3. 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`.
4. Require persisted `succeeded` state, then verify public health and the
   changed behavior.

Never invoke `akurai-ec2 release`, `deploy.sh publish|release|deploy`, 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.

## 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 with exact SHAs via git ls-remote
akurai_repo_tree        browse a repository's file tree at a ref/sub-path
akurai_repo_blob        read a bounded UTF-8 file at a ref/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. `akurai_repo_branches` returns each branch name, exact head SHA, and default marker. `akurai_repo_blob` returns bounded UTF-8 content plus the resolved reference and latest commit metadata. 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

Any clone of hosted Git is an editing source. AkurAI Build hosted Git is the publication source, and the queued immutable commit is the deployment source:

```text
local checks → local commit → git push (auto-queues run) → wait/promote → persisted success → acceptance
```

Trusted Titan checkouts may substitute `repo_sync → verify branch head → run_queue(commit)` for the push step.

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-08-07 runs as ONE hardened systemd unit on Titan (`akurai-build.service`, `AKURAI_WORKERS=1`, `ProtectHome=read-only`, `NoNewPrivileges`): the service also executes pipeline runs. A CI job therefore cannot swap the service binary or restart the unit. The self-pipeline's protected `deploy-production` job stages the package job's prebuilt binary plus its sha256 into `~/.local/share/akurai-build/deploy-staging/` and exits; the root-owned `akurai-deploy.path` host unit (source in `deploy/host/`, installed at `/usr/local/lib/akurai-deploy-agent.sh`) verifies the checksum, installs, restarts the service, health-gates for up to 60s, and rolls back to the previous binary automatically on failure. The restart briefly interrupts the MCP-visible controller; the deployment row records success at handoff.

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.