GitHub Integration

​

Overview

• 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

​

Repository Structure

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

​

Sync Behavior

​

Ankra → GitHub

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

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

git clone https://github.com/your-org/your-repo.git
cd your-repo

# Edit an add-on's values
vim clusters/my-cluster-<short-id>/stacks/monitoring/add-ons/prometheus/values.yaml

git add .
git commit -m "Increase Prometheus retention to 30d"
git push origin main

​

Pull Request Workflow

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

​

Ankra AI on Pull Requests

​

Ask Ankra in a Comment

@ankraai why does this change bump the Prometheus retention?
@ankraai review this
@ankraai is the failing pipeline on this PR caused by the values change?

• Ask (the default) - the reply is read-only. Ankra explains, reviews, and points out problems in the diff, but changes nothing; asked to act, it says the conversation is read-only and points you to the portal.
• Agent - when the fix is clear (a failing pipeline, a broken manifest, a small defect visible in the diff), the reply can propose a concrete, ready-to-apply fix: the root cause, the exact file changes as code blocks, and an offer to open the fix as a pull request. Ankra still does not run code or execute platform actions from the comment thread.

​

Merge when green

• Merge when green is on for the binding, and its AI mode is Agent - in Ask mode, or with the switch off, the request is refused and says which.
• The requester’s GitHub login is linked to a member of your Ankra organisation.
• The pull request’s head is not a fork.
• The newest Ankra Pipelines run for the head concluded successfully, and its gate step, if the definition declares one, passed.
• The run executed under plainly approved authority - one that fell back to an earlier approval, or none, is refused rather than merged under it.
• Ankra’s own AI review has not requested changes on that exact commit.
• No human reviewer’s most recent review is Changes requested - unlike the AI review’s check above, this one is not scoped to the current commit: a changes-requested left on an earlier push still blocks until the same reviewer clears it with a later review.

​

Turning It On

​

A Mention Gets No Reply

• Mention replies is off for the installation, or a repository rule for that repository has it off. A rule overrides the installation-wide switch, so check both.
• The comment does not contain @ankraai. Mentioning the app’s own login, @ankra-platform, is not enough.
• The comment was posted by a bot, or on an issue rather than a pull request.
• Ankra reacted with 👀 but never answered: the reply failed on Ankra’s side, for example because the AI provider did not answer. Nothing is posted in that case; mention @ankraai again to retry.
• No 👀 appeared at all: the mention never reached Ankra, so check the switches and the wording above before retrying.

​

Viewing Git History

​

In Ankra

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

​

In GitHub

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

​

Managing Access

​

Repository Permissions

​

Revoking Access

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

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

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

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.

​

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

​

CI/CD Integration

​

GitHub Actions Example

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

name: Deploy to Production
on:
  push:
    branches: [main]
    paths:
      - 'clusters/<cluster-name>-<short-id>/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Reconcile the cluster from its repository
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.ANKRA_API_TOKEN }}" \
            https://platform.ankra.app/api/v1/org/clusters/imported/$CLUSTER_ID/reconcile