AkurAI-Build

public

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

---
name: akurai-build
description: Operates the Titan-hosted AkurAI Build Git, CI/CD, community, cache, worker, metrics, and audit surfaces through the governed MCP contract.
compatibility: Requires the configured AkurAI Build MCP tools; production is reached through the AkurAI-VPN path.
license: MIT
---

# AkurAI Build operations

Read `../../../deploy.md` before every task. Use the configured `akurai-build` MCP tools for repository, pipeline, worker, cache, community, metrics, audit, artifact, and deployment operations. Direct shell/SSH/filesystem commands are read-only probes; never bypass the MCP contract or mutate a live service manually. Never expose bearer tokens, OIDC secrets, webhook secrets, database keys, or job secrets.

## Live topology and deployment path

The production path is:

```text
hosted Git or trusted Titan checkout
-> akurai_repo_sync / exact akurai_run_queue(commit)
-> verify -> immutable package (SHA-256 artifact)
-> deploy-production stages deploy-staging
-> root-owned akurai-deploy.path host agent
-> checksum install/restart/health gate/automatic rollback
```

Titan currently runs one hardened `akurai-build.service` execution surface with `AKURAI_WORKERS=1`. The worker pool is configurable for explicitly provisioned capacity; each worker owns one leased run at a time. Worker state includes heartbeat, drain state, lease expiry, current run, and completed runs. Draining lets an active lease finish and prevents new claims. Do not report queued, running, waiting, or package-only states as deployed; require persisted `succeeded` and verify the changed behavior.

Repositories are registered in encrypted SQLite. Existing registrations remain trusted administrator-owned. Native execution is allowed only when both controller-wide `AKURAI_ALLOW_NATIVE=1` and the repository's administrator-managed `trusted` flag are true. Otherwise use the restricted Docker executor. Docker jobs run with dropped capabilities, no-new-privileges, bounded CPU/memory/PIDs, read-only root, writable workspace/tmp, and no network unless explicitly declared.

## MCP inventory

Use the mounted `mcp__akurai_build_akurai_<name>` tools directly; the mounted schemas are authoritative. The current inventory is:

```text
akurai_doctor
akurai_repo_list akurai_repo_add akurai_repo_host
akurai_repo_sync akurai_repo_update akurai_repo_rename
akurai_repo_remove akurai_repo_visibility akurai_repo_protect
akurai_repo_branches
akurai_repo_tree akurai_repo_blob akurai_pipeline_validate
akurai_init akurai_release akurai_run_queue
akurai_runs akurai_run_show akurai_run_wait
akurai_run_logs akurai_run_retry akurai_run_cancel
akurai_run_promote akurai_artifact_get akurai_delivery_metrics
akurai_installation_register akurai_deployments_for_tenant
akurai_workers akurai_worker_drain akurai_cache_stats
akurai_cache_prune akurai_audit_events akurai_issue_list
akurai_issue_create akurai_issue_update akurai_issue_comment
```

`akurai_pipeline_validate` fetches a branch/tag or full commit, resolves it to an immutable commit, validates `.akurai.yml`/`akurai.yml`, and never queues a run. Use it before `akurai_run_queue`. `akurai_repo_branches` returns exact branch SHAs; pass the selected SHA to queueing. `akurai_repo_update` safely changes a registered URL and/or default branch.

`akurai_cache_stats` reports repository-ID-scoped cache entries, file counts, bytes, and modification evidence. `akurai_cache_prune` is bounded and supports `dry_run`; inspect first and never treat missing cache metadata as evidence of a hit. `akurai_worker_drain` toggles durable drain state. `akurai_audit_events` is a bounded read of consequential operation history including actor, repository/environment target, outcome, and timestamp. Promotion records the approver subject in addition to its timestamp.

The community tools use bounded pagination and `open|closed` issue states. Public repositories and community threads may be read anonymously by the service's public routes; private repository reads and every write require the repository permission contract. Static bearer automation and owner/admin sessions are platform administrators. Do not put credentials in repository URLs, arguments, Markdown, source, or logs.

## Authentication / OIDC

Authentication is implemented in `src/oidc.rs` against AkurAI IDP. The actual environment names are:

- `AKURAI_IDP_ISSUER` (default `https://auth.olibuijr.com`)
- `AKURAI_IDP_INTERNAL_URL` (back-channel URL; defaults to issuer)
- `AKURAI_IDP_CLIENT_ID`
- `AKURAI_IDP_CLIENT_SECRET`
- `AKURAI_IDP_REDIRECT_URI` (defaults to `<public-url>/auth/callback`)
- `AKURAI_IDP_ALLOWED_GROUPS` (optional comma-separated authorization groups)

Secrets belong only in protected service environment files or the configured secret store. There is no admin-email environment-variable contract.

## Source lifecycle

Any trusted Titan checkout may publish with `akurai_repo_sync`, followed by branch-head verification and `akurai_run_queue` for the exact SHA. A normal hosted-Git push queues through the repository webhook. Inspect `akurai_run_show`/`akurai_run_wait`; `waiting` requires explicit `akurai_run_promote`. Use `akurai_run_logs`, `akurai_delivery_metrics`, `akurai_audit_events`, and cache/worker operations to diagnose speed and governance without mutating production accidentally.