> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitOps

> Manage your clusters with GitOps using YAML files and include paths

<Note>
  Ankra makes it easy to manage clusters using GitOps. Define your cluster's configuration, manifests, and add-ons in YAML files, store them in Git, and let Ankra handle the automation.
</Note>

***

## What is GitOps?

GitOps is a way to manage your Kubernetes infrastructure using Git as the single source of truth. With Ankra:

* **Store configuration in Git** - Your cluster definitions, manifests, and add-ons live in your repository
* **Automatic sync** - Ankra detects changes and applies them to your clusters
* **Version control** - Track every change, roll back when needed, review via pull requests
* **Team collaboration** - Multiple team members can update configurations safely

***

## How It Works

Ankra uses **include paths** to let you split your configuration into multiple files or folders. This keeps your setup modular, maintainable, and easy to scale.

***

## Why Use Include Paths?

<CardGroup cols={2}>
  <Card title="CI/CD Integration" icon="rocket">
    Keep manifests and add-ons in separate files or folders for easy automation in your CI/CD pipelines. Update only what you need, and trigger deployments automatically.
  </Card>

  <Card title="Modularity & Reuse" icon="layer-group">
    Organize resources by team, environment, or feature. Reuse the same manifests or add-ons across different stacks or clusters.
  </Card>

  <Card title="Team Collaboration" icon="users">
    Let different teams own and update their own YAML files without merge conflicts. Everyone works from the same Git repository.
  </Card>

  <Card title="Scalability" icon="expand">
    Easily add new resources or stacks by dropping new YAML files into the right folder — no need to edit a giant config file.
  </Card>
</CardGroup>

***

## Repository Structure

Organize your Git repository with separate folders for manifests and add-ons:

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

***

## Cluster Definition Example

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

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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
      repository_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](/reference/importcluster).

***

## How Ankra Syncs Your Cluster

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

```mermaid theme={null}
flowchart LR
    A[Git Push] --> B[Ankra Detects Change]
    B --> C[Parse Include Paths]
    C --> D[Apply Manifests]
    D --> E[Deploy Add-ons]
    E --> F[Cluster Updated]
```

***

## Monitoring Sync Status

Track the status of your GitOps syncs in the cluster settings.

### Sync Status Banner

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:

1. **Fetching** - Pulling latest changes from Git
2. **Validating** - Checking YAML syntax and configuration
3. **Applying** - Deploying changes to the cluster
4. **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

1. Go to your cluster → **Settings** → **GitOps**
2. 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Missing Required Fields">
    Required configuration fields weren't provided.

    **Solution**: The error shows which fields are missing with examples of expected values.
  </Accordion>

  <Accordion title="Resource Conflicts">
    A resource already exists or conflicts with another definition.

    **Solution**: Check for duplicate resource names or conflicting configurations.
  </Accordion>
</AccordionGroup>

### Retrying Failed Syncs

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

***

## Best Practices

<Tip>
  **Keep related resources together.** Group manifests and add-ons by environment, team, or feature.
</Tip>

<Tip>
  **Use clear folder names.** Make it obvious what each folder contains (e.g., `manifests/`, `addons/`, `prod/`, `dev/`).
</Tip>

<Tip>
  **Automate with CI/CD.** Trigger Ankra syncs on pull requests or merges to main.
</Tip>

<Tip>
  **Review changes in Git.** Use pull requests to review and approve updates to your cluster configuration.
</Tip>

***

## 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 |

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

***

## Global Helm Registries

Ankra comes with a curated index of preloaded Helm charts that are ready to use out of the box. These registries power the add-on catalog in the Ankra platform.

<Card title="Community Contributions" icon="github" href="https://github.com/ankraio/ankra-global-resources">
  Want to add a Helm chart that would benefit the entire Ankra community? Submit a pull request to the **ankra-global-resources** repository. Your contribution will be available to all Ankra users.
</Card>

The [ankra-global-resources](https://github.com/ankraio/ankra-global-resources) repository contains:

* **Helm Registries** - Preloaded chart repositories that appear in the Ankra add-on index
* **Global Resources** - Platform-wide resource definitions

### Contributing a Helm Registry

1. Fork the [ankra-global-resources](https://github.com/ankraio/ankra-global-resources) repository
2. Add your Helm registry definition to the `helm_registries/` folder
3. Submit a pull request with a description of the charts and their use cases
4. Once merged, your charts will be available to all Ankra users

<Note>
  When contributing, ensure the Helm charts are well-maintained, secure, and provide value to the broader Kubernetes community.
</Note>

***

## Related

* [Stacks](/concepts/stacks) - Learn about organizing resources into stacks
* [Add-ons](/concepts/addons) - Install Helm charts as add-ons
* [Manifests](/concepts/manifests) - Deploy raw Kubernetes manifests

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.