> ## 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.
# Repository change requests
> Review proposed changes to an installation before they reach production: who proposes, who accepts, and how external proposers get a scoped token
A repository change request is a proposed edit to an [installation repository](/installs/repositories) 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. Change requests exist for cases where a change should be proposed, validated, and accepted before it reaches the installation: an agent fixing a misconfiguration, a partner preparing an update for a customer's environment, or an automated update that a regulated buyer wants to approve before rollout.
## 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.
```mermaid theme={null}
%%{init: {'flowchart': {'nodeSpacing': 55, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
you["You"] --> open
agent["An agent"] --> open
auto["Automated update"] --> open
open["Change request opened
(awaiting changes)"] --> validate["Validated automatically"]
validate --> ready["Ready for review"]
ready -->|accept| applied["Accepted
applied to the installation repository"]
ready -->|reject| rejected["Rejected
with a reason"]
ready -->|withdraw| withdrawn["Withdrawn
fork removed"]
ready -.->|no decision in time| expired["Expired"]
```
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 automation actor.** When automation needs to change repository-backed source or configuration, a change request is its default path. It attaches evidence to its proposal: a summary, the likely fix, and the resources it inspected. Automation 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 contribute to a managed fork 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.
Create the change request against the installation repository you want to change. This provisions the fork that work will be pushed to.
Request a token for the change request. You receive the fork's remote URL, a write token, and an expiry timestamp.
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.
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](/installs/install-repo#rollbacks).
## API
Manage repository change requests programmatically: open them, mint fork tokens, and accept, reject, or withdraw them.
Endpoints, parameters, response shapes, and try-it playground.
Mint API tokens for programmatic proposers and reviewers.
## Related topics
The git-backed model a change request proposes against.
Check status, logs, reviewed changes, and rollback paths.
How installs render, sync, expose status, and stream logs.
API tokens and authentication for proposers and reviewers.