AkurAI Build
Sign in with AkurAI ID
Menu

AkurAI-Build

public

Latest change 1488f88860de09bbb6791f4c67d3a8a8a3e0765f - Replace the JSON CI CLI with a full read/write akurai-build MCP tool set (repo add/host/sync/rename/remove/visibility/branches/tree, run queue/wait/retry/promote, artifact get, doctor, init); keep keygen/migrate/serve as plain CLI subcommands; update skill and deploy.md to the MCP tool set by Ólafur Búi Ólafsson

---
name: akurai-build
description: Operates the Titan-hosted AkurAI Build Git and CI/CD system through its maintained deploy script and Model Context Protocol tool set. Use for hosted repository migration/synchronization, repository registration, pipeline runs, logs, artifacts, promotions, health, deployment, rollback, Nginx-vhost setup, and release publishing.
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 and `deploy.sh help` 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 or deploy script 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`.

Use only the maintained entrypoint. It forwards to Titan when invoked elsewhere and automatically verifies source-tree synchronization before source-changing/checking commands:

```sh
~/Projects/AkurAI-Build/deploy.sh sync
~/Projects/AkurAI-Build/deploy.sh edge-probe
~/Projects/AkurAI-Build/deploy.sh mesh-recover  # restart Titan and EC2 VPN nodes, then verify private upstream
~/Projects/AkurAI-Build/deploy.sh http-smoke
~/Projects/AkurAI-Build/deploy.sh probe
~/Projects/AkurAI-Build/deploy.sh status-local
~/Projects/AkurAI-Build/deploy.sh status
~/Projects/AkurAI-Build/deploy.sh logs 100
~/Projects/AkurAI-Build/deploy.sh format
~/Projects/AkurAI-Build/deploy.sh clean-build  # only for pre-fix corrupt/stale Cargo artifacts
~/Projects/AkurAI-Build/deploy.sh recover-checks  # only after a timed-out/stale check
~/Projects/AkurAI-Build/deploy.sh check
~/Projects/AkurAI-Build/deploy.sh binfmt
~/Projects/AkurAI-Build/deploy.sh docker-smoke
~/Projects/AkurAI-Build/deploy.sh build-info
~/Projects/AkurAI-Build/deploy.sh deploy-local
~/Projects/AkurAI-Build/deploy.sh deploy
~/Projects/AkurAI-Build/deploy.sh rollback
```

Do not replace these with ad-hoc `ssh`, `systemctl`, `docker`, Nginx, certificate, package-manager, Git publication, database, artifact, or filesystem mutation commands. Never edit installed/runtime files manually.

## MCP tool set

Repository, pipeline, run, artifact, and promotion operations are MCP tools served over stdio (JSON-RPC `2025-06-18`) by:

```sh
~/Projects/AkurAI-Build/deploy.sh mcp
```

Register it once as a stdio MCP server: `command: "~/Projects/AkurAI-Build/deploy.sh"`, `args: ["mcp"]`. Call `tools/list` for the live schema. Tool set:

```
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_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

```sh
~/Projects/AkurAI-Build/deploy.sh lock
~/Projects/AkurAI-Build/deploy.sh publish "concise change summary"
~/Projects/AkurAI-Build/deploy.sh deploy
~/Projects/AkurAI-Build/deploy.sh vhost
```

Service deploys have a bounded readiness wait. Checks have hard process-group timeouts so a deadlock is killed and fails closed. `publish` maintains the repository-local GitHub author identity, checks, commits, and pushes GitHub `olibuijr/AkurAI-Build`; `deploy` checks again, builds, retains the previous binary, migrates transactionally, installs the skill, and restarts the hardened service.

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