AkurAI Build
Sign in with AkurAI ID
Menu

AkurAI-Build

public

Latest change cf7ca00627d8c2792168f66fbabdaffc170ef8d5 - docs: distinguish named and protected environments by fastcoder-scribe

{% extends "layouts/docs.html" %}
{% block title %}Documentation — AkurAI Build{% endblock %}
{% block docs_title %}AkurAI Build documentation{% endblock %}
{% block docs_summary %}A practical guide to the Git, pipeline, artifact, and release contracts owned by the AkurAI Build control plane.{% endblock %}
{% block docs_content %}
<section id="overview">
  <h2>What AkurAI Build owns</h2>
  <p>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.</p>
  <ul class="ab-docs-checklist">
    <li><b>Git-native input.</b> Every run resolves an explicit ref to an immutable commit.</li>
    <li><b>Bounded execution.</b> Docker is the default executor; native jobs require an explicit trust decision.</li>
    <li><b>Persisted evidence.</b> Run state, logs, artifact digests, approvals, and deployments survive the browser session.</li>
    <li><b>Private by default.</b> Public repository visibility is an intentional owner action.</li>
  </ul>
</section>

<section id="quick-start">
  <h2>Quick start</h2>
  <ol>
    <li>Add a repository with <code>akurai_repo_add</code>, or mirror a trusted Titan checkout with <code>akurai_repo_host</code>.</li>
    <li>Commit a versioned <code>.akurai.yml</code> at the repository root.</li>
    <li>Queue a run with <code>akurai_run_queue</code> and inspect the persisted result with <code>akurai_run_show</code>.</li>
  </ol>
  <pre><code>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/**]</code></pre>
  <blockquote>Jobs depend on the previous job by default. Set <code>needs: []</code> only when a job is an independent root.</blockquote>
</section>

<section id="repositories">
  <h2>Repositories</h2>
  <p>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.</p>
  <pre><code>akurai_repo_add
  name: payments-api
  url: https://git.example.com/team/payments-api.git
  branch: main</code></pre>
  <p>Hosted repositories clone from <code>https://akurai-build.olibuijr.com/git/&lt;name&gt;.git</code>. Authentication belongs in a credential helper—never in the URL.</p>
  <p>A successful <code>git push</code> to a hosted repository queues a pipeline run for its default branch automatically when the pushed revision carries <code>.akurai.yml</code>; repositories without a pipeline accept pushes without creating runs. External forges can additionally deliver webhooks to <code>/api/hooks/&lt;repository&gt;</code>.</p>
  <p>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.</p>
</section>

<section id="pipeline">
  <h2>Pipeline file</h2>
  <p>The repository-owned <code>.akurai.yml</code> is the complete execution contract. Jobs may declare dependencies, branches, matrix axes, caches, artifacts, environments, and approval requirements.</p>
  <div class="ab-docs-table-wrap">
    <table>
      <thead><tr><th>Field</th><th>Purpose</th></tr></thead>
      <tbody>
        <tr><td><code>needs</code></td><td>Names the jobs that must succeed first.</td></tr>
        <tr><td><code>branches</code></td><td>Restricts a job to explicit branch names.</td></tr>
        <tr><td><code>matrix</code></td><td>Expands bounded variants, including Linux architecture.</td></tr>
        <tr><td><code>artifacts</code></td><td>Retains matched output with digest and size evidence.</td></tr>
        <tr><td><code>environment</code></td><td>Associates a deployment with a named target; set <code>approval: true</code> to protect it.</td></tr>
        <tr><td><code>approval</code></td><td>Stops the job until an operator approves its named environment.</td></tr>
      </tbody>
    </table>
  </div>
</section>

<section id="execution">
  <h2>Job execution</h2>
  <h3>Docker jobs</h3>
  <p>Docker jobs run with dropped capabilities, <code>no-new-privileges</code>, bounded CPU, memory, and process counts, a read-only root filesystem, and no network unless <code>network: true</code> is declared.</p>
  <h3>Native jobs</h3>
  <p>Native execution requires the controller-wide <code>AKURAI_ALLOW_NATIVE=1</code> opt-in; the runner does not enforce trust per repository. Enable it only when every repository writer permitted to run pipelines is trusted, because native and secret-bearing jobs are privileged operations.</p>
</section>

<section id="artifacts">
  <h2>Artifacts</h2>
  <p>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.</p>
</section>

<section id="mcp">
  <h2>MCP workflow</h2>
  <p>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.</p>
  <pre><code>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</code></pre>
</section>

<section id="releases">
  <h2>Protected releases</h2>
  <p>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.</p>
</section>

<section id="security">
  <h2>Security model</h2>
  <ul>
    <li>SQLCipher state and secrets remain outside repositories and retained logs.</li>
    <li>API and Git requests use bounded bodies, timeouts, and constant-time credential checks.</li>
    <li>Browser mutations require an authenticated session and same-origin request.</li>
    <li>Paths, refs, artifact names, and repository names are validated before reaching Git or the filesystem.</li>
    <li>Secrets are exact-value redacted from retained job logs.</li>
  </ul>
  <blockquote>Repository writers are privileged. Pipeline commands are code, and code can intentionally transform or disclose any secret it receives.</blockquote>
</section>

<nav class="ab-docs-pagination" aria-label="Documentation completion">
  <a href="/">Back to homepage</a>
  <a href="/#explore">Explore public code <span aria-hidden="true">→</span></a>
</nav>
{% endblock %}