AkurAI Build
Sign in with AkurAI ID
Menu

AkurAI-Build

public

Latest change 9b227aaaf72c1a75fca3639c9c46acf437838cb2 - Add repo remove: unregister a repository and delete its hosted mirror 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 JSON CLI. 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, `deploy.sh help`, and `deploy.sh cli --help` before running anything. Mutations must use maintained commands. Direct shell/SSH/system commands are read-only probes only; after a successful probe, add the operation and a focused check to the CLI 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.

## JSON CI CLI

Run production operations through `deploy.sh cli`:

```sh
~/Projects/AkurAI-Build/deploy.sh cli doctor
~/Projects/AkurAI-Build/deploy.sh cli repo list --search app --visibility private
~/Projects/AkurAI-Build/deploy.sh cli repo add app https://github.com/org/app.git --branch main
~/Projects/AkurAI-Build/deploy.sh cli repo host app /home/olafurbui/Projects/app --branch main
~/Projects/AkurAI-Build/deploy.sh cli repo sync app /home/olafurbui/Projects/app
~/Projects/AkurAI-Build/deploy.sh cli repo remove app
~/Projects/AkurAI-Build/deploy.sh cli run app --git-ref main
~/Projects/AkurAI-Build/deploy.sh cli runs --repo app,worker --status failed,interrupted --trigger manual,webhook --search compiler --limit 20 --offset 0
~/Projects/AkurAI-Build/deploy.sh cli show 42
~/Projects/AkurAI-Build/deploy.sh cli wait 42 --timeout 3600
~/Projects/AkurAI-Build/deploy.sh cli logs 42 --failed
~/Projects/AkurAI-Build/deploy.sh cli retry 42
~/Projects/AkurAI-Build/deploy.sh cli promote 42 production
~/Projects/AkurAI-Build/deploy.sh cli artifact get 7 ./artifact.bin
~/Projects/AkurAI-Build/deploy.sh cli workers
```

Every query and mutation command returns `{ "ok": true, "data": ... }` or exits nonzero with `{ "ok": false, "error": ... }`. `repo list` filters by text/visibility. `runs` accepts comma-separated `--repo`, `--status`, and `--trigger` filters, exact `--git-ref`, free-text `--search`, `--limit`, and `--offset`; `/api/state` exposes the same run query shape. `AKURAI_WORKERS` configures 1–16 Titan workers and defaults to two in the service unit. Parse JSON and require `status == "succeeded"` before claiming a build or deployment succeeded. `waiting` requires explicit promotion; `queued` and `running` are incomplete.

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

`repo remove <name>` 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
`repo list`. Repositories registered by URL (no local mirror) are unregistered without a
mirror deletion.

## MCP queries

Launch the read-only Model Context Protocol server through the maintained entrypoint:

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

The newline-delimited stdio server exposes `akurai_repositories`, `akurai_runs`, `akurai_run`, and `akurai_workers`. Run filters accept strings, comma-separated values, or arrays for multi-project/status/trigger queries. Tool results are persisted database evidence; MCP never exposes protected secrets.

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