Skip to main content
The GitHub integration enables GitOps workflows, allowing you to store stack configurations in Git and maintain a full audit trail of infrastructure changes.

​
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

1

Navigate to Cluster Settings

Go to your cluster and click Settings → Repository tab.
2

Connect GitHub

Click Connect GitHub. You’ll be redirected to GitHub to authorize the Ankra GitHub App.
3

Authorize Access

Review the permissions requested:
  • Read access to metadata
  • Read and write access to repository contents
Click Authorize to grant access.
4

Select Repository

Choose an existing repository or create a new one. Ankra will create a cluster/ folder in this repository to store your configuration.
5

Configure Sync

Choose your sync settings:
  • Branch: Which branch to sync with (default: main)
  • Auto-sync: Whether to automatically sync changes

​
Repository Structure

When connected, Ankra creates the following structure in your repository: 
repository/
└── cluster/
    └── {cluster-name}/
        ├── stacks/
        │   └── {stack-name}/
        │       ├── values/
        │       │   └── {addon-name}.yaml
        │       └── manifests/
        │           └── {manifest-name}.yaml
        └── settings.yaml

​
Files Explained

PathDescription
stacks/{name}/values/Helm values files for each add-on
stacks/{name}/manifests/Raw Kubernetes manifests
settings.yamlCluster-level configuration

​
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

1

Clone the Repository

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

Edit Configuration

Modify values files or manifests:
# Edit an add-on's values
vim cluster/my-cluster/stacks/monitoring/values/prometheus.yaml
3

Commit and Push

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

Sync in Ankra

Navigate to your cluster’s GitOps page and click Sync to pull the changes, or wait for auto-sync if enabled.

​
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:
PermissionPurpose
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
Administration (read/write) (optional)Detect and, on request, fix the repository’s Actions workflow-token permissions so the first build can push to GHCR without a manual settings change
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.
Administration is optional. When granted, Ankra’s CI/CD tab can read whether the repository’s default GITHUB_TOKEN is read-only and offer a one-click fix to set it to read/write — a common cause of write_package: denied on the first build. Without it, Ankra still detects the problem and links you to the exact GitHub settings to change manually. Approve it under Settings → Applications → Installed GitHub Apps → Ankra → Configure.

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

​
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

Use Protected Branches: Require pull request reviews for the main branch to ensure all changes are reviewed.
Meaningful Commits: Write clear commit messages that explain why changes were made.
Separate Repositories: Use different repositories for different environments (dev, staging, prod).
Secret Management: Don’t store secrets in Git. Use Kubernetes Secrets or external secret management.

​
CI/CD Integration

Integrate with CI/CD pipelines:

​
GitHub Actions Example

name: Validate Ankra Config
on:
  pull_request:
    paths:
      - 'cluster/**'

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

​
Deployment Pipeline

name: Deploy to Production
on:
  push:
    branches: [main]
    paths:
      - 'cluster/production/**'

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 and we’ll help out.