GitOps

A change made only in a portal has no review step and no history your team controls. Connecting a Git repository to a cluster gives you both: Ankra writes the cluster’s Stacks to the repository, and commits you push are applied to the cluster. Sync runs both ways, and a repository is optional - a cluster without one is fully supported. How Ankra Works shows where Git sits in the overall model.

Repository Structure

There are two ways a cluster’s files end up in a repository, and they can look different. The layout Ankra writes. When you connect a repository, or change a cluster in the portal, CLI, API or through Ankra’s AI, Ankra writes the cluster to its own directory:

my-repo/
  clusters/
    my-cluster-<short-id>/
      my-cluster.yaml              # the cluster's ImportCluster definition
      .ankra-owned.json            # what Ankra last wrote (never edit or delete)
      stacks/
        monitoring/
          add-ons/
            kube-prometheus-stack/
              values.yaml
          manifests/
            monitoring-namespace.yaml

Edit these files and push; Ankra applies the change. What Ankra Writes Back to Git explains how it avoids overwriting your edits. A layout you write by hand. If you author the cluster definition yourself, for example to import a cluster from YAML, you choose the layout and point at it with include paths:

my-repo/
  manifests/
    namespace.yaml
    namespace.AGENTS.md
    rbac.yaml
  addons/
    ingress.yaml
    ingress.AGENTS.md
    monitoring.yaml
  import-cluster.yaml

The optional AGENTS.md sibling files hold per-manifest and per-add-on operational learnings for your team and Ankra’s AI - see Teach Your Agents with AGENTS.md.

Cluster Definition Example

Your import-cluster.yaml references files using include paths:

apiVersion: v1
kind: ImportCluster
metadata:
  name: my-cluster
spec:
  git_repository:
    provider: github
    credential_name: my-credential
    branch: main
    repository: my-org/my-repo
  stacks:
  - name: platform-stack
    manifests:
    - include: manifests/
    addons:
    - include: addons/

Ankra will automatically load and apply all YAML files from the manifests/ and addons/ folders. You can also include individual files for more control:

manifests:
- include: manifests/namespace.yaml
- include: manifests/rbac.yaml

Single-File Cluster Definition

For small or self-contained setups you can skip include paths and define everything inline in one file. Manifest and values content is embedded as base64:

apiVersion: v1
kind: ImportCluster
metadata:
  name: my-cluster
  description: Imported cluster with an inline stack
spec:
  git_repository:
    provider: github
    credential_name: my-git-credential
    branch: main
    repository: my-org/my-gitops-repo
  stacks:
  - name: secrets
    manifests:
    - name: secrets-namespace
      manifest_base64: <base64-encoded YAML>
      namespace: secrets
      parents: []
    addons:
    - name: external-secrets
      chart_name: external-secrets
      chart_version: 0.10.5
      registry_name: external-secrets
      registry_url: https://charts.external-secrets.io
      namespace: secrets
      configuration_type: standalone
      configuration:
        values_base64: <base64-encoded values.yaml>
      parents:
      - name: secrets-namespace
        kind: manifest

Use parents to control deployment order - a resource only deploys after its parents succeed. Prefer include paths once a cluster definition grows beyond a couple of resources. Every field of this file - stacks, manifests, add-ons, applications, parents, and encrypted paths - is documented in the ImportCluster YAML Schema.

Data Sources in the Cluster Document

The cluster’s metrics and log data sources live in the same file, as spec.prometheus_metrics and spec.log_source. Both are read back on every sync, so writing either block in Git connects the source and updates it - you do not have to configure it in the platform first:

spec:
  prometheus_metrics:
    endpoint: http://prometheus-operated.monitoring.svc.cluster.local:9090
  log_source:
    provider: loki
    endpoint: http://loki-gateway.monitoring.svc:80
    credential_name: loki-read

Credentials stay out of Git: a username, password, token or auth_scheme inside a source block is refused, and the credential is referenced by credential_name instead. Deleting a block does not disconnect the source - Git can create and update one, only the platform can disconnect it. See spec.prometheus_metrics and spec.log_source.

How Ankra Syncs Your Cluster

You update or add YAML files in your Git repository
Ankra detects the change and automatically syncs your cluster
All included manifests and add-ons are applied in the order you specify

What Ankra Writes Back to Git

Sync is two-way. Changes you commit are applied to the cluster, and changes made through the portal, the CLI, the API or Ankra AI are written back to the cluster’s directory in the repository, so Git stays the record. A platform write lands as a commit authored by ankra-platform[bot] (a change made in the portal, CLI or API) or by Ankra Reconciler with the subject Sync cluster state from Ankra (the reconciler exporting stored state).

The ownership manifest: `.ankra-owned.json`

Every cluster directory carries a file named .ankra-owned.json. Ankra rewrites it on each platform write. It is a record of what that write rendered - not an inventory of the directory, and not a claim on it:

paths lists the files the last write rendered. It bounds deletion: when a stack or add-on is removed, only files listed here are pruned. A file Ankra never rendered is never deleted, only reported.
contents maps each rendered file to a digest of the bytes Ankra itself last wrote there. It bounds overwriting: before writing a file, Ankra compares what is in Git with that digest. If they differ, the file was edited since, and Ankra keeps the Git version instead of replacing it.

Because the manifest is regenerated from each render, it grows when the cluster gains stacks or add-ons, and a write scoped to one stack may list a path it chose not to write. Neither means Ankra will overwrite that path; the digest decides.

Never delete or hand-edit .ankra-owned.json. It does not fail safe. With no manifest at head, Ankra has no record of what it wrote, so the overwrite boundary switches off and the next platform write replaces whatever is in Git. If it has been removed, restore it from Git history.

Hand-maintaining a file

To keep a value Ankra would otherwise render - an image tag pinned above a chart’s appVersion for a CVE fix, an updateStrategy, topologySpreadConstraints - edit the file in Git and merge it. Ankra syncs the change into the cluster, and from then on the file’s bytes in Git no longer match the digest Ankra recorded, so no platform write replaces them. This holds for every write path: portal, CLI, API, Ankra AI and the reconciler’s own export. Three limits apply today:

SOPS-encrypted files are not covered. Their committed bytes are ciphertext that cannot be reproduced from the render, so Ankra keys them on the embedded content fingerprint instead, and re-encrypts the file whenever its stored values change. A hand edit to an encrypted file sealed under the cluster’s .sops.yaml is imported like any other Git change and then re-sealed by Ankra’s next write - the values survive, the ciphertext does not, so expect one re-seal commit after rotating a sealed Secret by hand (see Rotating by API and SOPS).
.sops.yaml in the cluster directory has its own rule. Ankra rewrites the creation rules it generates there on every export, but it no longer replaces the file: rules you add by hand are kept, and kept above Ankra’s own. See Merging the SOPS configuration file below.
Preservation is silent. Ankra logs Preserving git content the platform did not write on its side, but the sync status still reads in sync and no portal, CLI or API surface lists the preserved paths yet. While a file is preserved, a change made to it in Ankra does not reach Git - make the change in Git instead, which also brings Ankra’s copy back in line.

Merging the SOPS configuration file

The .sops.yaml in a cluster directory has two authors, so it is not covered by the digest boundary above: it is merged on every platform write instead of replaced, and the file it writes opens with a header saying so.

Ankra owns only the rules it generates: a rule carrying a path_regex Ankra generates, an age key, and at most an encrypted_regex - and nothing else. Ankra rewrites those on every sync and lists them last in the file. While the cluster declares encrypted_paths, each generated rule carries an encrypted_regex built from the union of every declaration across the cluster’s stacks, rebuilt on every sync as the declarations change, so a sops -e that applies the rule seals only declared secret keys and leaves every other key readable. It is one union per cluster, so it is broader per file than what Ankra itself seals per resource: a key declared secret for any resource in the cluster is sealed in every matching file.
Every other rule is yours. It is preserved verbatim and kept above Ankra’s own. SOPS applies the first matching creation rule, so a rule of yours takes precedence over Ankra’s - including a deliberately keyless first rule, which is the supported way to keep a path out of encryption and make an external sops -e on it fail loudly rather than seal a file that must stay plaintext. Write its path_regex relative to the cluster directory, not the repository root: sops matches a rule against the file’s path relative to the directory holding the .sops.yaml it is using, so for the cluster’s file the path being tested is stacks/<stack>/add-ons/<add-on>/values.yaml. A rule written from the repository root never matches, and a refusal caused by nothing matching is an accident, not protection - see Checking that a keyless rule applies.
To override one of Ankra’s rules, write a rule that is not shaped like Ankra’s: keyless, using key_groups, carrying a field other than path_regex, age and encrypted_regex, or on a different path_regex. A rule that is a path_regex Ankra generates plus an age key, with or without an encrypted_regex, cannot be told apart from Ankra’s own output and is replaced whatever its age or encrypted_regex values are - that is what lets a key rotation or a changed declaration reach the file, and it happens silently. To keep your own recipients or your own encrypted_regex on a path Ankra covers, name the recipients with key_groups. The warning below spells it out.
Other top-level keys are yours too. stores, kms, shamir_threshold and anything else in the file are carried through untouched.
Ankra does not read these rules. Its own encryption is driven per resource by that resource’s encrypted_paths declaration, compiled to a SOPS encrypted_regex when the resource is sealed (see SOPS). The file exists for external tooling that runs sops against the repository.

A .sops.yaml Ankra cannot parse is left exactly as it is, rather than rewritten.

Checking that a keyless rule applies

sops looks for .sops.yaml by walking up from the current directory, not from the file it is given, and matches each path_regex against the file’s path relative to the directory holding that .sops.yaml. Test a rule from the repository root with an explicit --config, writing to stdout (never -i):

sops --config clusters/<cluster-directory>/.sops.yaml -e clusters/<cluster-directory>/stacks/<stack>/add-ons/<add-on>/values.yaml

What comes back says which rule decided. The wording is from sops 3.13.3 and is not a stable interface; an automated check should key on the positive control below rather than on the text.

Result	Meaning
`Could not generate data key: [empty key group provided]`	Your keyless rule matched first. The path is protected from a configuration-driven `sops -e`.
`error loading config: no matching creation rules found`	No rule matched at all, usually a `path_regex` written from the wrong base directory. The refusal is an accident, not protection.
`config file not found, or has no creation rules, and no keys provided through command line options`	`sops` found no `.sops.yaml` above the current directory. Pass `--config`, or run from inside the cluster directory.
Ciphertext on stdout	A rule with recipients matched first, or `--age` was given on the command line. `--age` bypasses the creation rules entirely, so a keyless rule does not stop it.

Pair the check with a positive control in the same run: a neighbouring file that only a rule with recipients covers must encrypt, or the refusal proves nothing about your rule. Ankra’s generated rules are written relative to the cluster directory (.*values\.yaml$ and .*manifests/.*\.yaml$), so on a cluster synced since that change they match and can serve as the control: a values file only they cover must encrypt. A .sops.yaml still carrying the older repo-rooted spellings (<cluster-directory>/.*values\.yaml$) predates the change - those rules match nothing, Ankra’s next write to the cluster replaces them, and until then a control needs a keyed rule of your own, written relative to the cluster directory like the keyless one.

The shape to avoid: one of Ankra’s own path_regex values, an age key, and nothing else except an encrypted_regex. A rule in that shape cannot be told apart from Ankra’s output, so the next platform write replaces it - with no signal anywhere. The sync succeeds, and no portal, CLI or API surface reports it. The only trace is the reconciler’s own Sync cluster state from Ankra commit, where the rule is simply gone from the diff.All three conditions have to hold together - that path_regex, an age key, and no field beyond those two and encrypted_regex - so the only rules at risk are those whose path_regex is character-for-character one of the two Ankra generates:

- path_regex: .*values\.yaml$
- path_regex: .*manifests/.*\.yaml$

The older repo-rooted spellings of the same two patterns, prefixed with the cluster’s own directory (<cluster-directory>/.*values\.yaml$, <cluster-directory>/.*manifests/.*\.yaml$), are read as Ankra’s too: clusters synced before the config-relative change still carry them, and the next platform write replaces them with the rules above. The examples below use that older spelling - the ownership test is the same for both.The trap is tidying. A deliberately keyless rule on one of those two patterns is yours and is kept - but give it an age key, to “complete” it or to seal that path with your own recipient, and it becomes Ankra’s shape and disappears on the next write. Adding an encrypted_regex of your own does not take it back out: that field is part of Ankra’s shape, so the rule is still replaced, and your selector with it:

# Kept - keyless, so not Ankra's shape.
- path_regex: <cluster-directory>/.*values\.yaml$

# Replaced silently - Ankra's shape: its path_regex, an age key, nothing else.
- path_regex: <cluster-directory>/.*values\.yaml$
  age: age1...

# Replaced silently too - encrypted_regex is part of Ankra's shape, whatever its value.
- path_regex: <cluster-directory>/.*values\.yaml$
  encrypted_regex: ^(password)$
  age: age1...

# Kept - same path, your own recipients, named with key_groups.
- path_regex: <cluster-directory>/.*values\.yaml$
  key_groups:
  - age:
    - age1...

Any one of these keeps a rule out of Ankra’s shape: leave it keyless, name recipients with key_groups, carry a field outside path_regex, age and encrypted_regex (unencrypted_suffix, for example), or write it on a path_regex Ankra does not generate. An encrypted_regex on its own does not: it is part of Ankra’s shape. The header Ankra writes at the top of the file states the same test. The paths in this example show the ownership test only; a rule you rely on sops to apply must be written relative to the cluster directory, as described above.

Removing the last encrypted_paths entry on a cluster deletes .sops.yaml, and your own rules with it. Ankra renders the file only while the cluster has encrypted content. Clear the last encrypted_paths entry from the last add-on or manifest that had one, and the next platform write stops rendering .sops.yaml, so the export prunes it from the cluster directory. Ankra never reads .sops.yaml back in, so there is no copy in the platform to restore from - recover it from Git history.This matters most in the case that leads you there: removing an over-broad entry is the fix for a chart field that was sealed and should not have been (see SOPS). If that entry is the cluster’s last one, keep a copy of .sops.yaml first, and re-commit your rules after Ankra’s next write.

When Git and the Platform Both Change

Because sync is two-way, the same resource can change on both sides between two syncs: someone edits a stack in the portal while a commit to the same stack lands in Git. Ankra does not guess which side you meant. On every sync Ankra compares three things: the head of the branch, the state stored in the platform, and the baseline both sides last agreed on. That comparison has four outcomes:

What changed since the baseline	What Ankra does
Only Git	Applies the commit to the cluster
Only the platform	Commits the change to Git
Both, on different resources	Merges them, applying the Git side and committing the platform side
Both, on the same resource	Records a conflict and waits for you

A conflict pins the cluster’s sync. Nothing further is applied from Git and nothing further is pushed to it until every conflicting resource has a decision. For each one you choose Git (the committed version wins and the platform change is dropped) or Cluster (the platform version wins and is committed over the Git version). Resolve conflicts from the GitOps section of the cluster settings, one resource at a time or all at once, or with the list_gitops_conflicts, get_gitops_conflict_diff and resolve_gitops_conflict MCP tools. Sync resumes on its own once the last conflict is decided. There is no setting that makes one side win automatically. If Git should be the authority for a cluster, make changes to that cluster only through Git: with no platform-side edits there is nothing to conflict with. If a platform write finds a commit in Git that Ankra has not imported yet, the change is saved in the platform but its push to Git is held back, and the next sync merges the two sides or raises a conflict as above.

Connecting a repository to a cluster that already has state

When you connect a repository to a cluster Ankra is already managing, Ankra first pushes the cluster’s current state to the repository as a commit named Connect GitOps repository, then starts syncing. Connect an empty repository, or one Ankra has written to before. A repository that already holds files at the paths Ankra renders, and has no .ankra-owned.json, has no overwrite boundary yet, so that first push can replace those files. You do not need a repository at all. With the native engine, Ankra reconciles stacks and add-ons from the state stored in the platform, and a cluster with no repository connected is fully supported. Connecting one adds Git as a second place to read and make changes; it does not change how the cluster is reconciled.

Monitoring Sync Status

Track the status of your GitOps syncs in the cluster settings. Navigate to your cluster → Settings → GitOps to see the current sync status:

Status	Description
Synced	All configurations are up-to-date with the repository
Syncing	A sync is currently in progress
Error	The last sync failed. Check error details below
Not Configured	GitOps is not yet connected to a repository

Sync Progress

During a sync, you’ll see the progress through these phases:

Fetching - Pulling latest changes from Git
Validating - Checking YAML syntax and configuration
Applying - Deploying changes to the cluster
Completed - Sync finished successfully

Manual Sync

Click Sync Now to trigger an immediate sync from your Git repository. Use this when:

You want to apply changes without waiting for automatic detection
Webhook delivery failed
You need to force a refresh

Sync History

View a complete history of all GitOps syncs for your cluster.

Accessing Sync History

Go to your cluster → Settings → GitOps
Scroll down to the Sync History table

History Table Features

The sync history table shows:

Column	Description
Status	Success, Failed, or Running badge
Source	How the sync was triggered (webhook or manual)
Commit	The Git commit SHA with a link to view in GitHub
Started	When the sync began (relative timestamp)
Triggered By	Who or what initiated the sync

Table Features:

Pagination: Navigate through history (10 entries per page)
Sorting: Click column headers to sort by any field
Commit Links: Click the SHA to view the commit in GitHub

Sync Metadata

Each sync entry includes detailed metadata:

Last Commit SHA: The exact commit that was synced
Sync Source: webhook (automatic) or manual
Timestamp: When the sync occurred
Retry Count: Number of retry attempts (if any)
IAC Files Link: Direct link to view the configuration files in your repository

Handling Sync Errors

When a sync fails, Ankra provides detailed error information to help you fix issues quickly.

Error Display

Failed syncs show:

Validation Errors: Issues with YAML syntax or configuration
Field-Level Guidance: Specific fields that need attention
Missing Fields: Required fields that weren’t provided
Typo Detection: Suggestions for misspelled field names

Common Error Types

Validation Errors

YAML syntax issues or invalid configuration values.Solution: Check the error details for the specific field and fix the YAML in your repository.

Missing Required Fields

Required configuration fields weren’t provided.Solution: The error shows which fields are missing with examples of expected values.

Resource Conflicts

A resource already exists or conflicts with another definition.Solution: Check for duplicate resource names or conflicting configurations.

Retrying Failed Syncs

Fix the issues in your Git repository
Commit and push the changes
Click Sync Now or wait for automatic detection
Monitor the new sync in the history table

Troubleshooting

If Ankra isn’t syncing as expected:

Issue	Solution
Sync not triggering	Check that Git credentials are valid and have repo access
Files not found	Verify all `include` paths exist in the repository
Invalid configuration	Ensure YAML files are syntactically correct
Wrong branch	Confirm the branch name in your cluster definition matches
Unsure which repository a cluster deploys from	Run `ankra cluster gitops status --cluster <name>`. It reports the configured repository and branch, and `observed_source` - the repository the last successful sync actually read. If they disagree, `source_mismatch` is `true`
A `prometheus_metrics` or `log_source` block you deleted keeps coming back	Removing the block is not a disconnect - the platform re-renders it. Disconnect the source in the cluster’s Settings → Integrations
A field you added to a data source block fails the sync	Only the fields in the ImportCluster schema are accepted; the error names the offending key. Credential fields (`username`, `password`, `token`, `auth_scheme`) are always refused - reference a credential by `credential_name`
A value you set in Git is reverted by a platform write	Check that `.ankra-owned.json` exists in the cluster directory - without it the overwrite boundary is off (What Ankra Writes Back to Git). Restore it from history, and report the reverting commit: its author, `ankra-platform[bot]` or `Ankra Reconciler`, tells support which write path produced it
A change made in the portal never reaches Git	The file is hand-maintained - its bytes in Git are not what Ankra last wrote, so Ankra preserves it. Make the change in Git; Ankra syncs it in and the file becomes writable again

Use the Ankra WebUI to see sync status and any errors. The Operations page shows deployment history and helps identify issues.

Stacks - Learn about organizing resources into stacks
Add-ons - Install Helm charts as add-ons
Manifests - Deploy your own Kubernetes YAML

Still have questions? Join our Slack community and we’ll help out.

Get Started

Concepts

Create and Run Clusters

Ship Your App

Stacks and Add-ons

Observe and Troubleshoot

Ankra AI

Connect Tools

Source Control

Security and Access

Cost and Backups

Organisation and Account

Reference

Repository Structure

Cluster Definition Example

Single-File Cluster Definition

Data Sources in the Cluster Document

How Ankra Syncs Your Cluster

What Ankra Writes Back to Git

The ownership manifest: `.ankra-owned.json`

Hand-maintaining a file

Merging the SOPS configuration file

Checking that a keyless rule applies

When Git and the Platform Both Change

Connecting a repository to a cluster that already has state

Monitoring Sync Status

Sync Status Banner

Sync Progress

Manual Sync

Sync History

Accessing Sync History

History Table Features

Sync Metadata

Handling Sync Errors

Error Display

Common Error Types

Retrying Failed Syncs

Troubleshooting

​Repository Structure

​Cluster Definition Example

​Single-File Cluster Definition

​Data Sources in the Cluster Document

​How Ankra Syncs Your Cluster

​What Ankra Writes Back to Git

​The ownership manifest: .ankra-owned.json

​Hand-maintaining a file

​Merging the SOPS configuration file

​Checking that a keyless rule applies

​When Git and the Platform Both Change

​Connecting a repository to a cluster that already has state

​Monitoring Sync Status

​Sync Status Banner

​Sync Progress

​Manual Sync

​Sync History

​Accessing Sync History

​History Table Features

​Sync Metadata

​Handling Sync Errors

​Error Display

​Common Error Types

​Retrying Failed Syncs

​Troubleshooting

​Related

Repository Structure

Cluster Definition Example

Single-File Cluster Definition

Data Sources in the Cluster Document

How Ankra Syncs Your Cluster

What Ankra Writes Back to Git

The ownership manifest: `.ankra-owned.json`

Hand-maintaining a file

Merging the SOPS configuration file

Checking that a keyless rule applies

When Git and the Platform Both Change

Connecting a repository to a cluster that already has state

Monitoring Sync Status

Sync Status Banner

Sync Progress

Manual Sync

Sync History

Accessing Sync History

History Table Features

Sync Metadata

Handling Sync Errors

Error Display

Common Error Types

Retrying Failed Syncs

Troubleshooting

Related