GitHub Integration

Install the Ankra GitHub App to keep cluster configuration in a GitHub repository, build Applications, run Ankra Pipelines, and have Ankra AI review and answer on pull requests.

You want your cluster configuration in a GitHub repository you can review and roll back, and you want Ankra to work where your team already works: on pull requests. Ankra connects to GitHub through the Ankra GitHub App. One installation covers the repositories you grant it, and every feature below uses it.

GitHub has the widest support of the three Git providers. Git Providers compares it with GitLab and Bitbucket Cloud feature by feature.

What the GitHub App powers

• Cluster GitOps - Ankra writes each cluster’s Stacks, add-on values and manifests to a folder in your repository and syncs changes you push back to the cluster. How the folder is laid out and how sync works is on the GitOps page.
• Applications - Ankra opens a setup pull request with a Dockerfile, chart and pipeline, builds on push, and deploys.
• Ankra Pipelines - runs on pushes, tags and pull requests.
• AI code review, @ankraai mention replies, PR previews and merge when green - see Ankra AI on pull requests.

---

Connect a repository to a cluster

1. Open the cluster's GitOps settings

   Go to your cluster and click Settings → GitOps.

2. Select the credential

   Pick the GitHub credential for the App installation that can reach your repository. If you have not installed the Ankra GitHub App yet, Ankra offers Install GitHub App; GitHub then asks which repositories the App may access.

3. Choose the repository and branch

   Choose the repository, then the branch from the repository’s own branch list.

4. Connect

   Click Connect Repository. Ankra writes the cluster’s folder to the repository and keeps it in sync from then on. GitHub delivers the App’s webhooks, so there is nothing to register by hand.

To see what changed, open the cluster’s GitOps page for the sync status and recent commits, or the repository’s own history on GitHub. GitOps explains the sync in both directions, conflicts, and how to monitor it.

---

Ankra AI on Pull Requests

The Ankra GitHub App can also take part in the pull requests of every repository it is installed on. The capabilities are switched on per installation under AI → Settings → Connections → Source control & AI review → GitHub, and each can be overridden for an individual repository with a repository rule.

AI code review is the canonical guide to those switches: what each one does, how repository rules layer over the installation-wide defaults, which model a review runs on, what the review posts, and when one is skipped. This page covers what is specific to GitHub.

Switch	GitHub specifics
AI review	For a repository connected to Ankra Pipelines, the review resolves the newest pipeline run of the reviewed commit before it falls back to a GitHub check run, and cites the run’s own facts - failing step, findings, gate verdict, build digest - see What a pull request gets.
Mention replies	Answers when someone mentions @ankraai in a pull request comment, with the change as context. See Ask Ankra in a comment below.
PR previews	GitHub only. Deploys a throwaway preview of an application’s pull request build - see PR preview environments.

Turning It On

1. Open the GitHub integration

   Go to AI → Settings → Connections → Source control & AI review and find the GitHub installation. Each installation has its own switches and AI mode.

2. Choose the installation-wide switches

   On the All repositories row, turn on AI review, Mention replies and PR previews as needed. They apply to every repository the installation covers. Merge when green sits in the row’s header next to AI mode, because it needs Agent mode to act; it has no per-repository rule.

3. Add repository rules for exceptions

   Add a rule for a repository to give it its own switches. A rule replaces the installation-wide switches for that repository; remove the rule and the repository follows them again.

Related repositories sits at the bottom of each installation’s panel and is GitHub-only, because the cross-repository search runs on GitHub code search. Use it to tell a review that two repositories belong together when nothing in your deploy already says so - a client and the API it calls, or a shared library and the service that consumes it. See Relating two repositories directly.

Ask Ankra in a Comment

Mention @ankraai anywhere in a pull request comment or review comment, and Ankra AI replies on the pull request with the diff and the pull request’s metadata as its context:

@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?

Ankra reacts to your comment with 👀 as soon as it picks the mention up, and the answer arrives as a new comment posted by ankra-platform[bot]. A mention always gets an answer while Mention replies is on: it is not subject to the draft, target-branch, and daily-budget rules that gate automatic reviews.

How far the answer goes depends on the integration’s AI mode:

• Ask (the default) - the reply is read-only. Ankra explains, reviews, and points out problems in the diff, but changes nothing.
• Agent - when the fix is clear, the reply can propose the exact file changes and offer to open the fix as a pull request. Ankra still does not run code or execute platform actions from the comment thread.

Only comments written by people trigger a reply. Comments from bots and comments on plain issues are ignored.

Merge when green

Mention @ankraai merge when green on a pull request and Ankra squash-merges it once its newest Ankra Pipelines run has passed and nothing blocks it. The request expires after 24 hours, and a new push invalidates it.

It is off by default. An organisation admin turns it on with the Merge when green switch on the installation’s row under Settings → Connections → Source control & AI review, and the installation’s AI mode must be Agent. It works on GitHub only. The full list of conditions a merge checks is in A human can say “merge when green”.

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

---

GitHub App Permissions

GitHub lists every permission the Ankra GitHub App requests on the install screen. The ones the features on this page depend on:

Permission	What Ankra uses it for
Contents (read and write)	Read and write cluster configuration, and commit the files of an application’s setup pull request
Metadata (read)	Read repository information
Pull requests (read and write)	Open setup pull requests, read pull requests for AI review, post reviews and mention replies, and merge when green. The PR shepherd merges a pull request Ankra opened only when merging is opted in
Workflows (read and write)	Commit a generated GitHub Actions workflow (.github/workflows/*). Only needed when a setup pull request carries one: a new application commits .ankra/pipeline.yaml by default instead
Secrets (read and write)	Install the private Ankra registry login (ANKRA_REGISTRY_USERNAME, ANKRA_REGISTRY_PASSWORD) that an application’s GitHub Actions workflow publishes with
Actions (read and write)	Read an application’s workflow runs and their logs
Checks (read and write)	Read the check runs on a commit when the AI review looks at its CI state, and publish the Ankra PR shepherd check on the pull requests Ankra opened

The App also requests read access to issues, commit statuses, packages, security events, vulnerability alerts and artifact metadata, and write access to Actions variables, Pages and repository hooks.

The App subscribes to these webhook events: push, pull_request, issue_comment, pull_request_review_comment, workflow_run and repository.

If the App was installed before a permission was added to it, GitHub shows a review updated permissions prompt on the installation. New permissions are not granted to an existing installation until an owner approves them - see Permission Errors.

---

Revoking Access

To revoke the GitHub App, go to GitHub Settings → Applications → Installed GitHub Apps, find Ankra, click Configure, then Uninstall (or change which repositories it can access).

---

Troubleshooting

Sync Failures

If sync fails, check that the Ankra App still has access to the repository, that the configured branch exists, and that the files are valid YAML. Monitoring sync status shows the last commit Ankra synced and any error.

Permission Errors

1. Go to GitHub Settings → Applications → Installed GitHub Apps (or Organization settings → GitHub Apps for an organisation).
2. Find Ankra and click Configure.
3. Make sure the repository is in the Selected repositories list. A repository created after the App was installed is not covered unless the installation was granted all repositories.
4. If GitHub shows a review updated permissions prompt, approve it.

HTTP 403 - Resource not accessible by integration on the first write of an application setup means the installation cannot write to that repository at all: the repository is not granted, Contents or Pull requests is missing, or updated permissions are still awaiting approval. Fix it with the steps above, then re-run setup.

A missing Workflows permission reads differently: GitHub answers refusing to allow a GitHub App to create or update workflow … without 'workflows' permission, and Ankra’s message names Workflows. It only happens when the setup pull request commits a .github/workflows file.

---

Next Steps

• Git Providers - what works on GitHub, GitLab and Bitbucket Cloud
• GitOps - the repository layout and how sync works
• AI code review - every review switch and what a review posts
• Ankra Pipelines - pipelines that run on your pushes and pull requests