Skip to main content
A per-installation repository as a single signed source of truth: dashboard, git, and API surfaces all commit to one auditable store of tracked files, which the cluster reads as rendered manifests
Every installation on Akua lives in its own private git repository. The repository is the source of truth for the install: your customer’s wizard inputs, the composition logic that turns those inputs into Kubernetes resources, and the rendered manifests your cluster actually applies. Dashboard edits, accepted change requests, and approved automation all become repository changes that Akua renders and syncs to the cluster. This page explains the model. For reviewed changes, see Repository change requests. For the operator checklist, see Operate an installation.

​
Why per-installation

A product on Akua can have hundreds of installations. Each one belongs to a different customer, runs in a different cluster, may pin to a different upstream version, and may carry its own ad-hoc tweaks. The per-installation repository keeps these isolated:
  • Customer A can edit their installation’s inputs.yaml without touching anyone else’s install.
  • A patch you make for Customer B stays scoped to their repository.
  • Each installation’s history is a normal git log (branchable, diffable, revertible), independent of every other install.
The alternative (one shared repository, many directories) would make customer isolation a feature you’d have to enforce. With separate repositories, isolation is the default.

​
What’s in the repository

your-install-id/
├── akua.toml          # Package metadata: name, version, dependencies
├── package.k          # Composition logic — turns inputs into resources
├── inputs.yaml        # The wizard values your customer set
├── upstream/          # Pinned vendored copy of the source package
└── manifests/         # Rendered Kubernetes resources (Akua applies these to your cluster)
File or directoryOwnerPurpose
akua.tomlYouPackage identity. Mostly stable; edited when bumping the upstream pin.
package.kYouThe composition layer. Adds install-scoped labels, can patch any field on any rendered resource, can append extra resources the upstream doesn’t include.
inputs.yamlCustomer + youThe wizard’s output. Editable from the dashboard wizard, the API, or directly via git.
upstream/AkuaA pinned snapshot of the product’s source. Vendored at provision time so renders are deterministic and offline-capable.
manifests/Akua (rendered)Output of package.k + inputs.yaml against upstream/. Regenerated on every change; never edit manually.

​
How it stays in sync with the dashboard

The repository and the dashboard are not two separate stores. They are two views over the same content. The dashboard wizard reads inputs.yaml; saving a wizard change writes a commit. Reviewed repository changes update the dashboard view too, and a reviewed revert rolls it back. In reviewed environments, prepare changes through a repository change request so Akua can validate and apply them through the approval path. Either way, the result is a repository commit that the dashboard and cluster both see.
  • A customer changes a value through the wizard: commit lands and appears in history.
  • A change request is accepted: Akua merges the fork and starts the normal render lifecycle.
  • Automation edits an install through an approved path: the repository history records the change.
The dashboard owns inputs.yaml: if a customer saves a wizard change while you are preparing a repository change, review the latest inputs before submitting your proposal. Use package.k for changes that must survive customer-driven wizard updates.

​
Rendering: pure, idempotent, offline

The render step turns package.k + inputs.yaml + upstream/ into manifests/. It has three properties worth understanding:
  1. Pure. Identical inputs always produce identical manifests, byte-for-byte. There’s no clock, no network, no secret material in the render context.
  2. Idempotent. Akua hashes the rendered manifests; if a render produces the same hash as the previous one, no commit is made and no rollout is triggered. Whitespace edits to inputs.yaml don’t churn history.
  3. Offline-capable. Because upstream/ is vendored, renders work without any external fetches. If the original source package becomes unavailable, your installations keep working.
Together these mean: re-running a render against the same commit always produces a no-op, and the install your cluster syncs to is fully reproducible from the repository alone.

​
Where the repository lives

Akua-managed installations are hosted at git.akua.dev/<your-org>/<install-id>.git. Repositories are private and isolated to your workspace. Authenticate with your dashboard token (use any string for the username; the token is the password). The dashboard’s Source tab on every installation shows the clone URL, the latest applied commit SHA, and a link into the repository’s history. To watch the resulting installation converge, see the installation lifecycle: its live state, status, pods, and logs.

​
Repositories and the wider package model

The per-installation repository is one slice of Akua’s package model. The same package.k + inputs concept applies to:
  • Products (today): the source you publish gets vendored into every installation.
  • Policies (planned): workspace-wide policy bundles that layer on top of per-install renders.
  • Repository change requests: agent-authored or human-authored forks of an installation’s repo, reviewed and accepted through Akua rather than landed directly. See Repository change requests.
The repository as a primitive (versioned, isolated, pure to render) is what makes those follow-on capabilities composable.

Customize an installation via git

Understand the repository editing model.

Repository change requests

Propose and review changes before they reach production.

Package versioning

How commit history maps to installations and how to roll back.

Repositories API

Endpoints, parameters, and try-it playground.