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

# GitHub Integration

> Connect GitHub repositories for GitOps workflows and configuration management

<Note>
  The GitHub integration enables GitOps workflows, allowing you to store stack configurations in Git and maintain a full audit trail of infrastructure changes.
</Note>

## Overview

Connecting GitHub to Ankra enables:

* **Configuration Storage:** Store Helm values and manifests in your repository
* **Version Control:** Track all infrastructure changes with Git history
* **GitOps Workflows:** Sync changes between Ankra and your repository
* **Audit Trail:** Full history of who changed what and when
* **Collaboration:** Use pull requests and code review for infrastructure changes

***

## Connecting GitHub

<Steps>
  <Step title="Navigate to Cluster Settings">
    Go to your cluster and click **Settings** → **Repository** tab.
  </Step>

  <Step title="Connect GitHub">
    Click **Connect GitHub**. You'll be redirected to GitHub to authorize the Ankra GitHub App.
  </Step>

  <Step title="Authorize Access">
    Review the permissions requested:

    * Read access to metadata
    * Read and write access to repository contents

    Click **Authorize** to grant access.
  </Step>

  <Step title="Select Repository">
    Choose an existing repository or create a new one. Ankra will create a `clusters/` folder in this repository to store your configuration.
  </Step>

  <Step title="Configure Sync">
    Choose your sync settings:

    * **Branch:** Which branch to sync with (default: `main`)
    * **Auto-sync:** Whether to automatically sync changes
  </Step>
</Steps>

***

## Repository Structure

When connected, Ankra creates the following structure in your repository:

```
repository/
└── clusters/
    └── <cluster-name>-<short-id>/
        └── stacks/
            └── <stack-name>/
                ├── README.md
                ├── add-ons/
                │   └── <addon-name>/
                │       ├── values.yaml
                │       └── AGENTS.md
                └── manifests/
                    ├── <manifest-name>.yaml
                    └── <manifest-name>.AGENTS.md
```

### Files Explained

| Path                                                      | Description                                                                 |
| --------------------------------------------------------- | --------------------------------------------------------------------------- |
| `stacks/<stack-name>/README.md`                           | The Stack's description                                                     |
| `stacks/<stack-name>/add-ons/<addon-name>/values.yaml`    | Helm values for the add-on                                                  |
| `stacks/<stack-name>/add-ons/<addon-name>/AGENTS.md`      | Operational learnings for the add-on - see [AGENTS.md](/platform/agents-md) |
| `stacks/<stack-name>/manifests/<manifest-name>.yaml`      | The raw Kubernetes manifest                                                 |
| `stacks/<stack-name>/manifests/<manifest-name>.AGENTS.md` | Operational learnings for the manifest                                      |

***

## Sync Behavior

### Ankra → GitHub

When you make changes in Ankra:

1. Changes are saved to the platform
2. Configuration is exported to the connected repository
3. A commit is created with the changes
4. You can see the commit in GitHub history

### GitHub → Ankra

When you make changes in GitHub:

1. Push changes to the configured branch
2. Ankra detects the changes
3. Configuration is imported and validated
4. Changes are applied to your cluster

***

## Using GitOps

### Making Changes via Git

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/your-org/your-repo.git
    cd your-repo
    ```
  </Step>

  <Step title="Edit Configuration">
    Modify values files or manifests:

    ```bash theme={null}
    # Edit an add-on's values
    vim clusters/my-cluster-<short-id>/stacks/monitoring/add-ons/prometheus/values.yaml
    ```
  </Step>

  <Step title="Commit and Push">
    ```bash theme={null}
    git add .
    git commit -m "Increase Prometheus retention to 30d"
    git push origin main
    ```
  </Step>

  <Step title="Sync in Ankra">
    Navigate to your cluster's GitOps page and click **Sync** to pull the changes, or wait for auto-sync if enabled.
  </Step>
</Steps>

### Pull Request Workflow

For production environments, use pull requests:

1. Create a feature branch
2. Make configuration changes
3. Open a pull request
4. Review changes with your team
5. Merge to trigger sync

***

## Viewing Git History

### In Ankra

Navigate to your cluster's **GitOps** page to see:

* Last sync timestamp
* Recent commits affecting this cluster
* Sync status and any errors

### In GitHub

View the full commit history in your repository to see:

* All configuration changes over time
* Who made each change
* Commit messages explaining changes

***

## Managing Access

### Repository Permissions

The Ankra GitHub App requests:

| Permission                     | Purpose                                                                                               |
| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **Contents (read/write)**      | Read and write configuration files, branches, and commits                                             |
| **Metadata (read)**            | Access repository information                                                                         |
| **Pull requests (read/write)** | Open the setup pull request when onboarding an application's CI/CD pipeline                           |
| **Workflows (read/write)**     | Commit the generated GitHub Actions workflow (`.github/workflows/*`) in the setup pull request        |
| **Secrets (read/write)**       | Install and restore the private Ankra registry login used by an application's GitHub Actions workflow |

<Note>
  **Pull requests** and **Workflows** are required for the application setup flow (Dockerfile, manifests, and CI/CD pipeline generation). GitHub treats `.github/workflows/*` as protected, so committing a workflow file needs the dedicated **Workflows** permission in addition to **Contents**.
</Note>

<Note>
  **Secrets** is required for Application CI/CD. Ankra writes `ANKRA_REGISTRY_USERNAME` and `ANKRA_REGISTRY_PASSWORD` as encrypted Actions secrets so the generated workflow can publish to the organisation's private registry. Approve it under **Settings → Applications → Installed GitHub Apps → Ankra → Configure**.
</Note>

### Revoking Access

To disconnect GitHub:

1. Go to cluster **Settings** → **Repository**
2. Click **Disconnect**

To revoke the GitHub App entirely:

1. Go to GitHub **Settings → Applications → Installed GitHub Apps**
2. Find Ankra and click **Configure**, then **Uninstall** (or adjust which repositories it can access)

***

## Troubleshooting

### Sync Failures

If sync fails, check:

1. **Repository Access:** Ensure the Ankra app still has access to the repository
2. **Branch Exists:** Verify the configured branch exists
3. **Valid YAML:** Ensure all configuration files are valid YAML
4. **Conflicts:** Resolve any merge conflicts in the repository

### Permission Errors

If you see permission errors:

1. Go to GitHub Settings → Applications → Installed GitHub Apps
2. Find Ankra and click **Configure**
3. Ensure the repository is in the "Selected repositories" list
4. If GitHub shows a **review updated permissions** prompt, approve it. New permissions added to the Ankra App (such as Pull requests or Workflows) are **not** granted to existing installations until an owner re-approves them.

<Note>
  `HTTP 403 - Resource not accessible by integration` means the installation token is missing a permission for the operation it attempted. Opening an application setup pull request requires **Pull requests (read/write)** and - because the pull request adds a `.github/workflows` file - **Workflows (read/write)**. Confirm both are granted on the installation (not just declared on the App), then re-run setup.
</Note>

### Out of Sync

If Ankra and GitHub are out of sync:

1. Navigate to the cluster's GitOps page
2. Click **Force Sync** to re-sync from the repository
3. Review any conflicts and resolve them

***

## Best Practices

<Tip>
  **Use Protected Branches:** Require pull request reviews for the main branch to ensure all changes are reviewed.
</Tip>

<Tip>
  **Meaningful Commits:** Write clear commit messages that explain why changes were made.
</Tip>

<Tip>
  **Separate Repositories:** Use different repositories for different environments (dev, staging, prod).
</Tip>

<Tip>
  **Secret Management:** Don't store secrets in Git. Use Kubernetes Secrets or external secret management.
</Tip>

***

## CI/CD Integration

Integrate with CI/CD pipelines:

### GitHub Actions Example

```yaml theme={null}
name: Validate Ankra Config
on:
  pull_request:
    paths:
      - 'clusters/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate YAML
        run: |
          find clusters -name "*.yaml" -exec yamllint {} \;
```

### Deployment Pipeline

```yaml theme={null}
name: Deploy to Production
on:
  push:
    branches: [main]
    paths:
      - 'clusters/<cluster-name>-<short-id>/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Ankra Sync
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.ANKRA_API_TOKEN }}" \
            https://platform.ankra.app/api/v1/clusters/$CLUSTER_ID/sync
```

***

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.