GitOps flow
When a deploy follows a git repository, the merge is the deployment, so the merge is the step that needs an
approval. Vaicoa offers two ways, both through the forgejo_git driver, tested against Forgejo 17 and Flux 2.9.
git.change: a pull request you approve
Section titled “git.change: a pull request you approve”- An agent or a person proposes a change, for example “set the replicas of
apps/web.yamlto 2” in a deploy repository. - The driver pushes a branch and opens a pull request. The plan is the commit’s tree hash plus the CI results.
- You approve. Your approval binds the tree hash.
- The driver merges itself, only after the required checks are green and stable for a while, and only if the branch
still has exactly that tree. If someone else landed on
mainmeanwhile, it stops withbase_moved; you propose and approve again. - Vaicoa triggers a Flux reconcile and checks that Flux applied the merge commit.
The agent may push branches but not merge. Files named *.sops.* are never touched. The forge token is sealed in the
core, never in the driver’s environment.
Who owns a field. An object carrying Flux’s label belongs to Flux. Values that live in git (replicas, image,
volume size) change only through git.change; a direct change would be rolled back at the next reconcile. What is
not in git (a rollout restart) changes directly. An object not managed by Flux the node changes directly, with a plan
computed beforehand.
git.tag: approving a release instead of a merge
Section titled “git.tag: approving a release instead of a merge”For trunk-based work: agents push to main, and only a release tag deploys. You approve the tag.
- A release bot is the only one allowed to set tags matching the release pattern (for example
v*), protected in Forgejo. An agent with write access can neither push such a tag nor create it through the API. - The plan shows the previous tag, the commits since then with their CI state and the agent run behind each (from the
Vaicoa-Run:commit trailer), the required checks and a diff summary. - Before you see it, the core refuses an unprotected pattern, a commit not on the default branch, red or pending checks, a red commit in the range, an existing tag, a version that does not increase, or too many commits.
- After the approval, the driver reads everything again. A new check result or a removed protection ends the op, and no tag is created. Otherwise the bot sets an annotated tag with the op, the approvers and the plan.
vaicoa-core checkwarns when a deploy follows such a repository by branch instead of by tag: then every merge would reach production without a release approval.
The playbook release.rollout builds on it: tag, wait for Flux, a canary step with part of the replicas, a health
check, and on failure the replicas go back (see operations processes).