Documentation

AkurAI Build documentation

A practical guide to the Git, pipeline, artifact, and release contracts owned by the AkurAI Build control plane.

What AkurAI Build owns

AkurAI Build is a single Rust service for authenticated Git hosting and continuous delivery. One controller records repositories, immutable revisions, jobs, logs, artifacts, approvals, deployments, and worker state.

Git-native input. Every run resolves an explicit ref to an immutable commit.
Bounded execution. Docker is the default executor; native jobs require an explicit trust decision.
Persisted evidence. Run state, logs, artifact digests, approvals, and deployments survive the browser session.
Private by default. Public repository visibility is an intentional owner action.

Quick start

Add a repository with akurai_repo_add, or mirror a trusted Titan checkout with akurai_repo_host.
Commit a versioned .akurai.yml at the repository root.
Queue a run with akurai_run_queue and inspect the persisted result with akurai_run_show.

version: 1
jobs:
  - name: test
    image: oven/bun:1.3
    network: true
    run:
      - bun install --frozen-lockfile
      - bun test

  - name: package
    needs: [test]
    image: oven/bun:1.3
    run: bun build src/index.ts --compile --outfile dist/app
    artifacts: [dist/**]

Jobs depend on the previous job by default. Set needs: [] only when a job is an independent root.

Repositories

Repository registration stores a stable name, Git URL, default branch, and visibility. Names are unique. Registration by URL keeps the upstream remote as the source; hosting creates an AkurAI Build-owned bare mirror from a trusted checkout.

akurai_repo_add
  name: payments-api
  url: https://git.example.com/team/payments-api.git
  branch: main

Hosted repositories clone from https://akurai-build.olibuijr.com/git/<name>.git. Authentication belongs in a credential helper—never in the URL. On the LAN they also clone over SSH with a key registered under SSH keys; every key is forced into akurai git-shell, which only runs git on hosted repositories with the same roles as HTTPS.

Any repository you can read can be forked under a new name (you become its admin, and it can pull from its upstream later); forge admins can host mirrors of external Git URLs that refresh every ten minutes. Search finds code across every repository you may read through akurai-index, and each repository has an Insights tab with contributors, weekly activity and the most changed files.

The repository workspace and each public repository provide stable ref/path links for trees, files, README content, and recent commits. Run history is server-paginated, filterable, shareable by URL, and links to canonical run detail pages.

Pipeline file

The repository-owned .akurai.yml is the complete execution contract. Jobs may declare dependencies, branches, matrix axes, caches, artifacts, environments, and approval requirements.

Field	Purpose
`needs`	Names the jobs that must succeed first.
`branches`	Restricts a job to explicit branch names.
`matrix`	Expands bounded variants, including Linux architecture.
`artifacts`	Retains matched output with digest and size evidence.
`environment`	Associates a deployment with a protected target.
`approval`	Stops promotion until an operator approves it.

Pipelines can also declare schedules (five-field cron, UTC, read from the default branch and queued once per matching minute), reuse job lists with include (a version: 1 file with jobs, from this repository or another hosted one, parameterised with ${{ inputs.NAME }} and with), and declare secrets that resolve from the repository's own secrets (stored values or PassVault entries, managed by admins under /api/repos/<name>/secrets) before the worker's AKURAI_SECRET_* environment. cache paths work for native jobs too.

Job execution

Docker jobs

Docker jobs run with dropped capabilities, no-new-privileges, bounded CPU, memory, and process counts, a read-only root filesystem, and no network unless network: true is declared.

Native jobs

Native execution is for trusted repositories only and requires the controller's production opt-in. Repository writers can execute pipeline code, so native access and secret-bearing jobs are privileged operations.

Artifacts

Artifact records belong to an immutable run and job. AkurAI Build stores the relative path, SHA-256 digest, byte size, and retained file location. Promotion uses recorded outputs from successful dependency jobs rather than rebuilding unknown bytes.

MCP workflow

Agents and operators use the configured AkurAI Build MCP tools for control-plane state. Each response is structured JSON; queued or running work is incomplete until a persisted terminal state is observed.

akurai_repo_list     # discover repositories
akurai_repo_branches # inspect remote refs
akurai_run_queue     # pin and queue a revision
akurai_run_wait      # wait for terminal or approval-required state
akurai_run_show      # inspect jobs, artifacts, and deployments
akurai_run_logs      # read bounded retained logs
akurai_run_promote   # approve one protected environment

Protected releases

A protected deployment waits after its dependency jobs succeed. Approval resumes only the named environment on that immutable run. A successful release requires persisted success, a healthy service, and revision confirmation; queued, running, or waiting states are not completion.

Security model

SQLCipher state and secrets remain outside repositories and retained logs.
API and Git requests use bounded bodies, timeouts, and constant-time credential checks.
Browser mutations require an authenticated session and same-origin request.
Paths, refs, artifact names, and repository names are validated before reaching Git or the filesystem.
Secrets are exact-value redacted from retained job logs.

Repository writers are privileged. Pipeline commands are code, and code can intentionally transform or disclose any secret it receives.