AkurAI Build
Sign in with AkurAI ID
Menu

AkurAI-Build

public

Latest change 7255093e06e11217a8aa00ce4b6f336d3a5fa654 - Add named service identities and akurai_repo_protect by Ólafur Búi Ólafsson

---
name: akurai-build-ops
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 `~/Projects/AkurAI-Build/deploy.md` before every task. This TencentDB Skill is the canonical operating procedure; do not look for a filesystem `SKILL.md`. Repository, pipeline, run, artifact, and promotion operations may go through the `akurai-build` MCP tool set, or directly through shell/SSH/system commands when that is more direct. Adding an operation to the MCP tool set and updating this skill is recommended when you need it repeatedly, but direct commands do not require an MCP round-trip first.

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.

Use hosted Git and the AkurAI Build MCP release/run path for deployment. `deploy.sh publish` is a legacy source-publication helper, while its `release` and `deploy` commands are retired; do not deploy through direct Build HTTP or manual service/filesystem mutations. 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 when convenient. The installed binary's stdio protocol, direct HTTP, or `deploy.sh cli|mcp` are also acceptable when the mounted tools are not available or a direct call is simpler. The mounted tool schema is authoritative when present; 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_protect     protect default branch (merge queue only) and set owner subject
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, you may update the MCP contract and deploy it through an already-supported pipeline path, or bypass the older server directly with raw stdio, direct HTTP, or an installed-file edit as convenient.

## 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.


## MCP argument contract (exact)
- `akurai_run_show` / `akurai_run_wait` / `akurai_run_logs` / `akurai_run_retry` / `akurai_run_cancel` take `{ "id": <number> }` — the run id, NEVER `run_id`, never empty.
- `akurai_run_queue` takes `{ "repository": "<name>", "wait": true }` and returns the run inline when it finishes within the blocking budget.
- `akurai_repo_sync` / `akurai_repo_host` require `source`: the absolute Titan checkout path.
- Known server defect: `akurai_runs` may ignore its `repository` filter and return other repositories' runs — filter client-side by the `repository` field of each row.