Customize an installation via git

Edit your installation directly in a git repository: change inputs, override resources, and roll out updates with a push

Every installation you create on Akua gets its own private git repository. Cloning it gives you direct, version-controlled access to the deployment configuration: the inputs your customer set in the wizard, the rendered Kubernetes resources, and the upstream package source. Push a change and Akua rolls it out to the cluster.

Most customers never need to touch this. The dashboard wizard and the values editor cover the common cases. The git repository is the escape hatch for the moments where you need to do something the UI doesn’t expose: patch a resource, add a sidecar, swap an image registry, or pin a version.

Find your installation’s repository

Open your installation in the dashboard. The Source tab shows the clone URL and the latest deployed commit.

# The URL has the form https://git.akua.dev/<workspace-org>/<install-id>.git
git clone https://git.akua.dev/your-org/your-install-id.git
cd your-install-id

The repository requires authentication. Your dashboard token works as the password; use any string for the username.

The repository is private and isolated to your workspace. Only your team can clone or push.

What’s inside the repository

You’ll edit inputs.yaml (the wizard values) for everyday changes and package.k (composition logic) for advanced ones. manifests/ is rendered output; never edit it. akua.toml and the vendored upstream/ copy round out the layout. For the full file-by-file breakdown and who owns each file, see Installation repositories.

Common edits

Change a value

Edit inputs.yaml, commit, push.

# Bump the replica count
$EDITOR inputs.yaml
git commit -am "scale replicas to 5"
git push

Akua re-renders manifests/ from the new inputs and rolls out the change to your cluster. The dashboard’s deployment status updates as the cluster converges.

Override a single field on a rendered resource

When inputs.yaml doesn’t expose what you need, edit package.k. The composition layer lets you patch any field on any resource without forking the upstream package.

# package.k — example: add a node selector to every Deployment
_patched = [r | {
    if r.kind == "Deployment":
        spec.template.spec.nodeSelector: { "node-pool": "high-memory" }
} for r in _upstream]

Commit, push, deploy.

Add a resource the upstream doesn’t include

Append it to the _extras list in package.k:

_extras = [
    {
        apiVersion: "v1"
        kind: "ConfigMap"
        metadata.name: input.appName + "-feature-flags"
        data: { enableNewUI: "true" }
    }
]

The new resource ships alongside the upstream’s resources on the next push.

Updating from upstream

When the upstream package publishes a new version, you can pull it into your installation without losing your edits:

1. Bump the upstream pin

   Edit akua.toml to point at the new upstream version.

2. Re-vendor

   Run akua vendor to refresh the upstream/ directory.

3. Test, commit, push

   Your edits in package.k and inputs.yaml carry over. The upstream change merges into manifests/ on the next render.

Rollbacks

The repository is a normal git history. Roll back by reverting:

# Roll back to the previous deployed commit
git revert HEAD
git push

Akua re-renders and the cluster converges to the reverted state.

What Akua overwrites

manifests/ is regenerated on every push; never edit it by hand. inputs.yaml can be rewritten when a customer changes wizard values from the dashboard, so put changes that must survive customer edits in package.k. package.k, akua.toml, and upstream/ are never overwritten. See how the repository stays in sync for the full model.

Related topics

Customizing inputs

Multi-source values editor and per-install overrides.

Installation repositories

The model behind the per-install git repository.

Package versioning

How commit history maps to deployments.

Products

Sellable deployment configurations.