.ankra/pipeline.yaml; it is the primary path, and the guide says exactly which pieces are in place today. Until its build and publish stages run in the cluster, the generated GitHub Actions workflow below is what publishes your image, and the two coexist on every commit.
Ankra Pipelines
CI in your cluster: triggers, a Job per stage, check runs, artifacts, and what a pull request can and cannot change.
Migrate from GitHub Actions
Convert a workflow, GitLab CI file, Bitbucket pipeline or CircleCI config and review the notes.
Bring your own CI (GitHub Actions)
Ankra Applications generates a GitHub Actions pipeline that builds your source repository, scans the image, and publishes it to your organisation’s private registry. The generated Kubernetes manifests already reference that image and the matching pull secret. Nothing about it changes when you add an Ankra pipeline to the same repository: the workflow’s checks keep their names, the pipeline’s isAnkra pipeline, and Ankra keeps reading the workflow’s results for publish readiness, push-to-deploy and previews.
The Ankra registry is private. Ankra provisions its project, GitHub Actions credentials, and Kubernetes pull credentials automatically.
How it works
1
Connect the repository
Create an Application from a GitHub repository. Ankra analyses the source and prepares the missing Dockerfile, Kubernetes manifests, and workflow.
2
Review the setup pull request
The pull request adds
.github/workflows/build-and-publish.yml and manifests under .ankra/manifests/. Monorepos get one scoped workflow per application.3
Merge and build
Merging the pull request runs the workflow. It tests the source, builds the image, pushes it to your organisation’s project on
registry.ankra.cloud, and scans it with Trivy.4
Pull requests build but do not publish
The workflow also runs on
pull_request, where it tests, scans the source, and builds the image without pushing it - so an unmerged branch never puts artifacts in your registry. The image scan follows the push, so it runs on branch builds only.5
Deploy
Deploy the Application to a cluster. Ankra checks that an image was published before starting the deployment.
Registry authentication
Ankra installs these encrypted GitHub Actions secrets on the application repository:
The robot is minted per application when the application is set up, so no two applications share a registry login. Rotate or revoke it from the application’s Settings → Image registry, or with
ankra application registry robot rotate|revoke - see Robot accounts.
The generated workflow uses the secrets with docker/login-action. It does not use GITHUB_TOKEN package permissions and does not publish a public package.
For Kubernetes pulls, Ankra creates an ankra-registry-pull Docker registry secret in each managed namespace. Generated Deployments include:
Your own registry
An Application that declares its own registry publishes there instead. The workflow logs in with the secret names the declaration gives (defaulting to theANKRA_REGISTRY_* pair), the generated Deployments reference the pull Secret it names, and Ankra creates that Secret in the deploy namespace from the registry credential the declaration names.
Ankra does not write the login secrets for a registry you operate unless you hand it robot management there: the robots are yours to administer, and overwriting a push robot with the credential Ankra holds would deny every later build. Publish readiness reports whether the named secrets exist. Name an admin_credential_name on the declaration to have Ankra mint a push robot for the application on your registry and write that into the secrets, or opt in with manage_actions_secrets: true to have it write the declared credential.
Image retention
The Ankra registry does not keep every image forever. Each organisation project carries a retention policy that Harbor runs once a day: an artifact is kept while it was pushed within the last 30 days, and the three most recently pushed tagged versions of every repository are kept whatever their age - so a component nobody has built in months still holds its last three releases. Everything else goes: older tagged images beyond the last three, and the untagged leftovers of overwritten tags once they are 30 days old. Harbor’s garbage collection reclaims the storage afterwards. Two consequences worth planning for:- A rollback can only reach a version that is still in the registry - one of the last three, or one pushed in the last 30 days.
- A workload still running an image older than that keeps running, because the image is cached on its node, but it cannot be rescheduled onto a fresh node once the image is gone. Redeploy long-lived workloads from a recent build.
Existing applications
Reconcile an Application after the registry cutover. Ankra updates its image URL, replaces a legacy build workflow or manifest with the private registry version, and restores missing repository secrets. You can inspect readiness in the application’s Pipelines section or from the CLI:Converting an existing workflow
Ankra converts a GitHub Actions workflow, a GitLab CI file, a Bitbucket Pipelines file or a CircleCI config into.ankra/pipeline.yaml. Ask Ankra AI in the portal chat or through the MCP server: cicd_convert_workflow_to_pipeline answers with the pipeline, a note for everything it could not map one to one, and a validation verdict; cicd_validate_pipeline_yaml checks a definition you wrote or edited. Steps that only installed cloud credentials or a registry login are dropped with a note, because the pipeline gets those from Ankra, and a third-party step the mapping table does not know becomes a stage that fails until you replace it.
For an application already connected to Ankra, GET/POST .../pipeline and .../pipeline/migrate do this in one call instead: read what builds it today, convert, and open the pull request - see Migrate an existing application with one call. The disposition itself only switches once that pull request merges, and a later push that adds or removes .ankra/pipeline.yaml or a workflow file on the default branch re-evaluates it automatically on GitHub.
The migration guide carries the full mapping table, what each source format loses, what to review afterwards, and how to run both side by side until you trust the pipeline. The pipeline.yaml reference documents every key.
Troubleshooting
The workflow cannot log in
The workflow cannot log in
Open the application’s Pipelines section. If Ankra cannot restore the repository secrets, approve the updated Ankra GitHub App Secrets permission and retry the fix.
The registry project is not ready
The registry project is not ready
Registry projects are provisioned automatically. The background reconciler retries missed provisioning. If readiness remains blocked after a few minutes, contact support.
The image push is denied
The image push is denied
Confirm that the workflow logs in to the host shown in the Application image URL and uses
ANKRA_REGISTRY_USERNAME and ANKRA_REGISTRY_PASSWORD. Reconcile the Application to replace a legacy workflow.Pods report ImagePullBackOff
Pods report ImagePullBackOff
Reconcile the Application and check the target namespace for
ankra-registry-pull. Ankra rotates and reapplies pull credentials automatically.Deploy is blocked
Deploy is blocked
Ankra blocks deployment until it can verify a published image in the organisation registry. Check the latest GitHub Actions run, then retry after the image push succeeds.
Next steps
Ankra Pipelines
Run the same lifecycle inside your own cluster.
Applications
Connect a repository and follow the Application lifecycle.
GitHub integration
Review the GitHub App permissions used by Ankra.
Pipeline Agents
Add read-only deployment and health reporting to your CI workflows.
SOPS Encryption
Encrypt other secrets stored in GitOps.