Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.akua.dev/llms.txt

Use this file to discover all available pages before exploring further.

A proposed change packet enters a review desk with accept, reject, and withdraw controls; only an accepted change lands on the installation repository HEAD and the append-only audit trail, while reject and withdraw never reach the repo
A repository change request is a proposed edit to an installation repository that someone reviews before it takes effect. Instead of writing directly to the installation, a proposer opens a change request against a fork of the repository. The change is validated, surfaced for review, and applied only when an authorized reviewer accepts it. This is the review gate behind sensitive changes to an installation. You still push everyday edits straight to the repository over git. Change requests exist for the cases where a change should be proposed and reviewed first: an agent fixing a misconfiguration, a partner pushing an update into a customer’s environment, or an automated update that a regulated buyer wants to approve before it reaches their cluster.

​
Why changes are reviewed

The installation repository is the source of truth for what runs on a cluster: the wizard inputs, the composition logic in package.k, and the pinned package version. Editing any of those changes the live installation. For some changes you want a deliberate checkpoint before that happens. Repository change requests give you that checkpoint:
  • Nothing lands without review. A proposed change sits in a fork until someone accepts it. Until then the installation is untouched.
  • The proposer and the accepter can be different. An agent or a partner can prepare a change without being able to apply it. Accepting is a separate, grantable permission.
  • Every decision is recorded. The proposal, its validation result, and the accept, reject, or withdraw decision are kept as a durable record alongside the repository’s git history.
This matters most when a change comes from somewhere other than your own keyboard. Agent-authored fixes and partner-pushed updates are proposals by default, so a person stays in control of what reaches production.

​
The lifecycle

A change request moves through a small set of states from the moment it opens to the moment it is accepted, rejected, withdrawn, or expires. While a change request is open, the proposer pushes work to the fork and Akua validates it. A change request that fails validation surfaces the problem instead of becoming acceptable. A request that no one acts on expires on its own, so stale proposals do not pile up against an installation.

​
Who can propose a change

A change request records who created it, so reviewers can weigh the source:
  • You. Prepare a change for a teammate to review, or stage a change you want recorded before it lands.
  • An agent. When an agent needs to change repository-backed source or configuration, a change request is its default path. An agent attaches evidence to its proposal: a summary, the likely fix, and the resources it inspected. The agent reads existing change requests first to avoid duplicating work already in progress.
  • The platform. Automated updates, such as a new image tag or a refreshed package version, can arrive as proposals rather than landing silently.
  • An external proposer. A CI job or a partner’s backend can open a change request against an installation it does not otherwise own, using a scoped token (below).

​
The external proposer token

A change request is backed by a fork of the installation repository. To let an external proposer push work to that fork, you mint a short-lived token scoped to the fork alone. The token grants write access to the fork’s git remote and nothing else. It cannot touch the parent installation, other repositories, or anything outside the fork. Tokens are short-lived: they expire within one hour at most, and you choose a shorter window when you need one.
1

Open a change request

Create the change request against the installation repository you want to change. This provisions the fork that work will be pushed to.
2

Mint a fork token

Request a token for the change request. You receive the fork’s remote URL, a write token, and an expiry timestamp.
3

Hand the token to the proposer

The CI job, agent, or partner pushes its proposed changes to the fork remote using the token. The token’s reach is limited to that fork.
4

Review and decide

Once the proposer has pushed, the change is validated and becomes ready for review. Accept, reject, or withdraw it.
The token is the handoff that lets a proposer who does not own the installation contribute a change safely. The review gate still decides whether that change ever reaches the cluster.

​
Reviewing a change: accept, reject, withdraw

A change request that is ready for review has three terminal actions:
  • Accept. Akua validates the change and applies it to the parent installation repository. Accepting kicks off the apply as a background operation you can follow to completion. Accepting can require its own grant and a separate approval, so being able to read or prepare a change does not imply being able to accept it.
  • Reject. Decline the change and record a reason. The reason is kept with the change request for the audit record and review history. The installation is unchanged.
  • Withdraw. Pull back a change request that is still editable. Withdrawing removes the fork. Use this when a proposal is no longer needed or was opened by mistake.
Only an accepted change reaches the installation. Rejecting and withdrawing both leave the installation exactly as it was.

​
What happens on accept

When you accept a change request, Akua revalidates the proposed change, merges it into the installation repository, and rolls the result out to the cluster the same way any other repository edit deploys. The accept runs as a background operation, so you can start it and watch the installation converge. Because the change merges into the installation repository’s normal git history, it is versioned, diffable, and revertible like any other commit. If an accepted change turns out to be wrong, you roll it back the same way you would roll back any installation edit.

​
API

Manage repository change requests programmatically: open them, mint fork tokens, and accept, reject, or withdraw them.

API reference

Endpoints, parameters, response shapes, and try-it playground.

Authentication

Mint API tokens for programmatic proposers and reviewers.

Installation repositories

The git-backed model a change request proposes against.

Customize an installation via git

Edit inputs, patch resources, and roll back changes directly.

Agents and repositories

How agents propose changes instead of writing to production.

Permissions and security

Grants and approvals that separate proposing from accepting.