Ankra Pipelines

​

Why CI belongs in your cluster

• Runners are a second fleet. GitHub-hosted runners are shared and rate limited; a self-hosted runner pool is one more set of machines to size, patch and pay for. A pipeline step is a Job on nodes you already have, scheduled under the quota and node selectors you set, and never at the expense of a deploy - the agent runs pipeline work in its own worker pool.
• Credentials live in CI secrets. A workflow needs registry logins, cloud credentials and deploy tokens as repository secrets, copied per repository and readable by any workflow that names them. In a pipeline definition those are references the platform resolves, and the sections that grant them are protected: a pull request can rewrite what a pipeline does, and cannot widen what it may touch.
• Publish happens before the gate. A workflow that pushes an image and scans it afterwards has already published a vulnerable image by the time the scan fails. The pipeline vocabulary separates build, scan, gate and publish so that nothing is published that the gate did not pass.
• The evidence is somewhere else. Run history, logs, scan artifacts and the check on the commit all lived on the CI provider. A pipeline run is an Ankra object: ankra pipeline get, live logs, artifacts in your own backup vault, and the same status on GitHub, GitLab or Bitbucket.

​

What is in place today

• The definition: .ankra/pipeline.yaml (apiVersion: ankra.io/v1, kind: Pipeline) with its parser, validator and dry-run planner - see the pipeline.yaml reference.
• Conversion of an existing GitHub Actions, GitLab CI, Bitbucket Pipelines or CircleCI definition into a pipeline, from chat or the MCP server - see Migrate from GitHub Actions.
• The organisation’s CI settings (which cluster runs pipelines, parallelism, image allow-list, retention, image gate) and its pipeline policy (the authority ceiling an administrator sets).
• The runs API and the ankra pipeline commands: dispatch, list, get, cancel, re-run, live step logs, artifacts, the stored definition, schedules.
• Triggers from push, pull request and tag deliveries on GitHub, GitLab and Bitbucket Cloud, deduplicated across redeliveries, with a recorded reason whenever nothing runs.
• In-cluster execution of run stages on the organisation’s CI cluster: a hardened Job per step in ankra-ci, a per-run workspace volume, keyed cache volumes, service sidecars, network tiers, resource ceilings, timeouts, live logs, and one automatic retry of Ankra’s own failures.
• SCM feedback: one Ankra pipeline check run per run on GitHub with a real conclusion and a Cancel button, a commit status on GitLab and Bitbucket, a comment fallback when the GitHub App lacks checks:write, and the pipeline section of the single status comment on the pull request.
• Step logs and declared artifacts stored in the organisation’s backup vault, listed and downloaded through the API and CLI.

• Connecting a repository to a pipeline. The lane that connects a repository and writes .ankra/pipeline.yaml through the setup pull request has not shipped. Until it does, a push to a repository records repository_not_onboarded and the by-application pipeline commands answer not found.
• Reading the committed file at each commit. The definition a run executes is the stored definition of record (ankra pipeline definition put); commit the same file so the two do not drift.
• The runners for checkout, build, scan and verify stages, and the platform-side settling of gate, publish and every other kind that does not run in the cluster. Today run is the stage kind that executes end to end.
• Delivering declared secrets and credentials into a step, and the run identity that permissions mints.
• Runs for pull requests from forks, schedules firing, and the user-declared retry block being applied.

​

How a run happens

1. Trigger. A verified delivery from GitHub, GitLab or Bitbucket Cloud - a branch push, a pull request opened, synchronised or reopened, or a tag - is normalised into one event and decided in a fixed order: is the repository connected, is the head trusted, is there a cluster to run on, is there a definition, does the definition’s on: block accept the event. A dispatch from the CLI, the API or an agent goes through the same decision. Every answer is recorded, so a push that started nothing still says why (the reason tokens).
2. Plan. The planner turns the definition and the event into the step DAG: which stages survive the trigger and stage filters, how a matrix fans out (at most 64 legs per stage), what each step depends on, which if: conditions can be settled now. Nothing is dropped silently - a filtered stage is recorded with a reason code, and a run whose every stage is filtered out is recorded as concluded with outcome skipped.
3. Dispatch. Steps are claimed org-fairly, never global FIFO: organisations are served in order of how many steps they already have running, inside each organisation’s own parallelism cap. The dispatcher resolves the cluster per step - the organisation’s CI cluster, otherwise the staging cluster it already nominated for AI work - and probes that the cluster’s agent advertises the run_pipeline_step job before sending anything.
4. Run. The agent renders the step’s own Kubernetes objects from the signed payload - it never applies what the platform sent verbatim - and runs a hardened batch/v1 Job. Output streams live while the step runs; the complete log and the declared artifacts are uploaded to your backup vault when it concludes.
5. Settle. The settle loop records the verdict, unblocks the steps that waited on it and concludes the run when nothing is left. Only Ankra’s own failures are retried, once; a non-zero exit is the step’s verdict and is final.
6. Report. The Ankra pipeline check run (or commit status) is updated on every change, and the pipeline section of the pull request’s status comment with it.

​

Prerequisites

• A connected repository. The repository is connected through the Ankra GitHub App, GitLab, or Bitbucket Cloud, so Ankra receives its webhooks. Pipelines are repository-scoped with an optional link to an Application; a repository with nothing to build can have a pipeline too.
• A CI cluster. An organisation administrator sets ci_cluster_id in the organisation’s CI settings. Without one, the staging cluster the organisation nominated for AI work is used; with neither, a provider event records no_ci_cluster and nothing runs.
• The agent’s ci worker pool. The cluster’s agent runs pipeline steps in a third scheduler that is off by default. Set the chart value ci_worker_count above zero (AGENT_CI_WORKER_COUNT); an agent with the pool disabled does not advertise the pipeline job names, and the platform refuses a step for that cluster up front instead of dispatching it.
• Optionally, a backup vault. Step logs and artifacts are stored as objects in the organisation’s oldest ready backup vault. An organisation without one still runs its steps; it keeps no durable log or artifact, and the step’s own outcome is unaffected.
• For check runs, checks:write. Without it the GitHub App cannot create a check run, and the run’s status is carried by a comment on the pull request instead - the comment says so and names the permission.

​

Your first green run

curl -X PUT https://platform.ankra.app/api/v1/org/ci-settings \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"ci_cluster_id": "<cluster-id>"}'

helm upgrade ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
  --namespace ankra \
  --reuse-values \
  --set ci_worker_count=2

apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "my-service"
on:
  push:
    branches:
      - "main"
  pull_request:
    branches:
      - "main"
concurrency:
  group: "my-service-${{ ankra.ref }}"
  cancel_in_progress: true
workspace:
  size: "10Gi"
  access: "rwo"
defaults:
  image: "golang:1.26"
  timeout: "20m"
  network: "egress-https"
stages:
  - name: "fetch"
    kind: "run"
    run: |-
      set -eu
      git clone --depth 1 https://github.com/my-org/my-repo.git .
      git fetch --depth 1 origin "$ANKRA_HEAD_SHA"
      git checkout --detach "$ANKRA_HEAD_SHA"
  - name: "test"
    kind: "run"
    run: "go test ./..."
    needs:
      - "fetch"
    resources:
      cpu: "2"
      memory: "4Gi"

ankra pipeline validate --application my-service

ankra pipeline definition put .ankra/pipeline.yaml --application my-service
git add .ankra/pipeline.yaml && git commit -m "Add the Ankra pipeline" && git push

ankra pipeline run --application my-service --sha "$(git rev-parse HEAD)" --wait
ankra pipeline list --application my-service
ankra pipeline logs <run-id> --application my-service --step test --follow

​

Organisation CI settings

​

Logic is open, authority is closed

• permissions - the API scopes the run identity is minted with.
• secrets and credentials - each declared binding, by name, source and key.
• on.pull_request.fork_policy.
• defaults.network and a stage’s network when it is above egress-https.
• runs_on on every stage - cluster, node selector, tolerations, runtime class - and resources.gpu.
• A gate stage’s approval roles and required stages, an approval stage’s roles and minimum approvals, an agent stage in agent mode and its tool profile, a webhook stage’s URL, an external stage’s provider and workflow.
• The environments block - data policy, verification, rollout and gate per environment.

​

What a step runs as

• Network tiers. none (the default) denies all egress. egress-https permits outbound port 443 to every destination except the cloud metadata endpoint. services is deny-all plus the run’s own pods; the sidecars a step declares are containers in its own pod, reached over loopback by name. A step that needs both outbound HTTPS and a separate service pod has no tier to name yet.
• Image policy. A run stage’s image is checked against ci_allowed_image_prefixes on the platform and again by the agent before anything runs.
• Resources. A step requests exactly what it limits. It may ask for at most 8 CPU cores, 32 GiB of memory and 4 GPU devices, and a GPU step must name a runs_on.node_selector, so it is refused here rather than left Pending until it times out.
• Reserved names. A step may not set environment variables beginning ANKRA_, the loader and PATH variables, or the image builder’s own BUILDKIT*, BUILDCTL, ROOTLESSKIT and DOCKER_CONFIG.
• Forks. A pull request whose head lives in a fork - or whose provenance the delivery could not establish - is refused with fork_policy_pending until the fork policy lane ships. The default fork_policy is read_only: a run with no secrets, no credentials and no identity beyond reading itself.
• Permissions. pipelines.read covers listing and reading runs, logs, artifacts, the stored definition, schedules and validation; pipelines.operate covers dispatch, cancel and re-run; pipelines.manage covers replacing the stored definition, creating, changing and deleting schedules, the pipeline policy and its approvals, and a dispatch with a --spec-file override.

​

When something fails

• Yours, never retried automatically. step_failed (the script exited non-zero), step_refused (the definition asked for something the policy or the renderer refuses - an image outside the allow-list, a missing script, too much compute), and timeout. A step that ran out of time did run; running it again is a retry policy to declare. The retry: block is validated and carried to the agent but not applied yet, so today a non-zero exit is final.
• Ankra’s, retried once. agent_infra (the cluster could not create the namespace, bind the volume or pull the image), worker_lost (the agent claimed the step and stopped reporting), result_malformed, agent_offline, agent_never_started (no agent claimed the step inside its timeout - check that the cluster is connected and ci_worker_count is above zero), execution_vanished and stranded. Each of these writes the next attempt instead of a conclusion, up to two attempts in total; the second failure concludes the step as infra_error, and the check run settles as action_required naming the class - Ankra failing never reads as your code failing.
• Timeouts. A stage runs under its timeout, or defaults.timeout, or 30 minutes; the ceiling is 6 hours and a longer value is clamped and recorded. The agent stops a step at its deadline with a 60-second grace, and a reaper on the platform sweeps every 30 seconds for steps two watchdogs missed - a step five minutes past its deadline, an agent that has not checked in for ten.
• Cancel. ankra pipeline cancel <run>, POST …/pipeline-runs/{run_id}/cancel, or the Cancel button on the check run while the run is live. A run that is cancelled concludes with outcome cancelled.
• Re-run. ankra pipeline rerun <run> (add --failed-only to re-run only the steps that did not succeed and whatever depends on them), POST …/pipeline-runs/{run_id}/rerun, or GitHub’s own Re-run button on the check. A re-run is a new run with rerun_of_run_id pointing at the old one; the old run’s outcome stays the record of what happened.

​

Limits and defaults

​

Bring your own CI (GitHub Actions)

​

Commands and API

​

What comes next

• Connecting a repository and writing .ankra/pipeline.yaml from the setup pull request; reading the committed file at each commit; retiring a generated workflow through a reviewable pull request.
• The runners for checkout, build (rootless BuildKit by digest), scan and verify; the platform-settled gate over persisted findings and publish as a re-tag of the digest the gate approved; previews deployed by digest.
• Secrets and credentials delivered into steps; the per-run identity that permissions mints, so a step can call the ankra CLI with exactly the authority the default branch granted.
• The built-in ankra/* step library behind uses:, organisation step templates, and custom_tool/<name> steps.
• The agent, approval, webhook, automation, ankra and external stage kinds; on.webhook inbound dispatch tokens.
• Fork policy - read_only runs with no secrets, no push and no egress - so public repositories can accept contributions safely.
• Schedules firing, the user-declared retry block, cache retention sweeps, and a run page in the portal.
• Environments hydrated from restore points, verification stages (HTTP probes, smoke scripts, k6 load tests, PromQL assertions, restore verification), promotions with approvals, and canary rollouts through Traefik weighted traffic.

​

Next steps