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.

A successful git push to a hosted repository queues a pipeline run for its default branch automatically when the pushed revision carries .akurai.yml; repositories without a pipeline accept pushes without creating runs. External forges can additionally deliver webhooks to /api/hooks/<repository>.

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.

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.