Ankra Pipelines

​

Before your first run

• A connected repository. The repository is connected through the Ankra GitHub App, GitLab, or Bitbucket Cloud, so Ankra receives its webhooks - and then connected to Ankra Pipelines itself, which is self-service: automatically when it backs an Ankra Application, or with one call for a bare repository (below). Pipelines are repository-scoped with an optional link to an Application; a repository with nothing to build can have a pipeline too. A Bitbucket Cloud repository gets its webhook when you connect it to Ankra Pipelines with a Bitbucket credential, and its pull requests start runs only once that credential grants Bitbucket’s pullrequest scope - see Granting the pull request permission.
• 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.
• An agent that advertises pipeline steps. The CI cluster’s agent runs pipeline steps in a third scheduler that is off by default - ci_worker_count (AGENT_CI_WORKER_COUNT) is 0 on every cluster until someone raises it. An agent with the scheduler off does not advertise the pipeline job names at all, so the platform refuses a step for that cluster up front instead of dispatching it. Set the count through Ankra, per cluster, and Ankra re-renders that agent’s own release; never helm upgrade the agent by hand (below).
• An approved definition. A pipeline’s protected sections - its secrets, credentials, permissions, network tier, placement, resources, timeout, caches, services and a gate stage’s with: - carry no authority until an organisation administrator approves the definition on the default branch. Until one does, a run still executes, with none of them: the check run and the pull request comment carry “No administrator has approved any authority for this repository yet, so this run executes with none.” Approve before the first run that needs any of it (below).
• 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.
• Somewhere to keep the objects - and you already have it. A scan stage’s reports, the findings a gate reads, the complete step log and every declared artifact are objects, and they need a bucket. An organisation with no ready backup vault of its own is lent one: Ankra keeps them in a vault the platform owns, under a key prefix of your organisation’s own, with the same retention, the same per-object download links and the same reaper. Nothing to provision before a first run.
• A vault of your own, when where the objects live matters. Register one for data residency, for a bucket only your own credentials reach, or simply because cluster backups, restore points and ankra migrate data need one - those never use the platform’s vault. A ready vault of your own takes precedence automatically, from the next step onward (below).

​

Connect a repository, push, see the run

ankra backup vaults provision ci-artifacts --credential upcloud-main --region europe-1 --wait

ankra backup vaults create ci-artifacts --endpoint https://s3.example.com --bucket ankra-ci

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>"}'

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

ankra cluster agent ci set --workers 2 --cluster <cluster-name>

apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "orders-api"
on:
  push:
    branches:
      - "main"
  pull_request:
    branches:
      - "main"
    fork_policy: "read_only"
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
workspace:
  size: "10Gi"
  access: "rwo"
defaults:
  image: "golang:1.26"
  timeout: "30m"
  network: "egress-https"
permissions:
  contents: "read"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "test"
    kind: "run"
    image: "golang:1.26"
    run: "go run gotest.tools/[email protected] --format testname --jsonfile test-results.json -- ./..."
    needs:
      - "checkout"
    test_results:
      - format: "go-test"
        path: "test-results.json"
  - name: "build"
    kind: "build"
    needs:
      - "test"
    build:
      dockerfile: "Dockerfile"
      platforms:
        - "linux/amd64"
      build_args:
        - "VERSION"
      provenance: true
      sbom: true
  - name: "scan"
    kind: "scan"
    needs:
      - "build"
    scan:
      scanners:
        - "semgrep"
        - "checkov"
        - "trivy"
      fail_on:
        checkov: "none"
        semgrep: "error"
        trivy: "app"
  - name: "gate"
    kind: "gate"
    needs:
      - "scan"
    gate:
      require_stages:
        - "scan"
  - name: "publish"
    kind: "publish"
    with:
      image: "harbor.ankra.cloud/orders/orders-api"
    needs:
      - "gate"
    when:
      events:
        - "push"

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 definitions get <definition-id>
ankra pipeline definitions approve <definition-id>

ankra pipeline run --wait
ankra pipeline list
ankra pipeline logs <run-id> --step checkout --follow

ankra pipeline run --application my-service --sha "$(git rev-parse HEAD)" --wait

ankra pipeline get --head-sha "$(git rev-parse HEAD)" --trigger pull_request --latest --wait --timeout 45m

ankra pipeline get <run-id> --watch -o json

​

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, after one of its own: a delivery’s commit arrives proven by the provider, a dispatch’s does not, so the ref it names is resolved against the repository’s own host and a caller-supplied head_sha is accepted only as that reference’s tip or a provable ancestor of it. Every answer is recorded, so a push that started nothing still says why (the reason tokens).
2. Plan. The planner first decides which definition it is planning: on GitHub it fetches .ankra/pipeline.yaml at the run’s own head commit and uses that for the run’s logic, falling back to the stored definition (with a diagnostic) if the read fails, and recording which source won; on GitLab and Bitbucket Cloud the stored definition is always what runs. A dispatch that carried its own definition (--spec-file, spec_yaml) outranks both: the override is stored verbatim on the run, and the planner and the dispatcher both render from it. Protected authority is resolved separately and never from the head file - nor from an override, which is content nobody committed. It then turns that 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, and - for a pull request that touches a protected section - which authority the run actually executes under (see Logic is open, authority is closed). 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. A stage whose kind has no executor on this build - preview, agent, approval, webhook, automation, ankra, external and verify - is skipped right here, with reason kind_unavailable and a sentence naming the kind and the wave that ships its executor, so a run that declares one still concludes instead of holding itself and its concurrency group open forever.
3. Dispatch. Steps are claimed org-fairly, never global FIFO: organisations are served in order of how many steps they already have running, and a run already at its own step cap is passed over for the next run’s step rather than holding the queue (see Capacity and concurrency). 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. Dispatch is also the point where a step’s deferred if: is evaluated and its remaining ${{ steps.<key>.outputs.<name> }} and needs.<stage>.* references are interpolated into run, env, with, image, working_directory and the stage’s own outputs:, now that the steps it waited for have concluded: a condition that reads false concludes the step skipped, and a reference that still cannot be resolved concludes it infra_error naming the field, rather than handing a container a literal ${{ }}. Both happen before anything is revealed, so a step about to be skipped spends no secret. Declared secrets and credentials are resolved into one-time, per-step reveal grants at this point, never written into the payload itself.
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. A checkout step clones the run’s commit with a pinned public git image, reading a revealed credential only if the host it is cloning from matches; a run step executes your script. Output streams live while the step runs; the complete log and the declared artifacts are uploaded to your backup vault when it concludes, through presigned URLs minted at dispatch. The vault is the organisation’s own oldest ready one, and an organisation with none is granted uploads into the Ankra-managed default vault instead; the step’s execution says which - pipeline_artifacts: "granted" or pipeline_artifacts: "granted (Ankra-managed default vault)". Only when there is no ready vault on either side does a step get no upload grants at all, recording pipeline_artifacts: "unavailable: This organisation has no ready backup vault, so pipeline step logs and artifacts have nowhere to be stored" - live output is unaffected, and everything archival is lost.
5. Settle. The settle loop records the verdict, unblocks the steps that waited on it and concludes the run when nothing is left. Each pass re-stamps the run’s own heartbeat, so a build that legitimately takes hours is no longer failed out from under you by the platform’s stale-run reaper at twenty minutes. Only Ankra’s own failures are retried, once; a non-zero exit is the step’s verdict and is final. A concluded build step’s digest is stamped as the application’s build observation, ranked below your own CI’s, so push-to-deploy, previews and rollback already read a pipeline-built image. gate and publish settle in the same pass: gate reads the run’s own persisted scan findings against your organisation’s policy, tightened per scanner by the fail_on each required scan stage declared and recording the digest it actually judged, and publish re-tags that digest into your real repository as sha-<7> - refusing outright if the build’s digest is a different one, or if the gate recorded none.
6. Report. The Ankra pipeline check run (or commit status) is updated on every change, naming the authority the run executed under when it differs from what the head asked for. On Bitbucket Cloud each kind of run keeps a commit status key of its own, so a tag, pull request or dispatched run on a commit no longer overwrites the branch run’s result there: ankra/pipeline for a push, ankra/pipeline/pull-request, ankra/pipeline/tag, ankra/pipeline/dispatch for a manual, API or agent dispatch, and ankra/pipeline/schedule, and a re-run keeps its original’s key. On a pull request the same run state and the same authority sentence populate the pipeline section of Ankra’s one status comment. The run’s outcome also leaves the pull request: pipeline_run_failed, pipeline_run_succeeded, image_gate_blocked, preview_ready and preview_failed are ordinary Ankra notification kinds, so they reach whichever Slack, Teams, PagerDuty or webhook destination your routing rules send them to.

​

Which component a build belongs to

1. build.component, when the stage declares it. The value is the name of a component the application records.
2. The stage name, otherwise: a stage called build-<component> belongs to that component.
3. The application’s one component, for a single-component application, whatever the stage is called.

stages:
  - name: build-portal          # release bundle for host deploys, attributed by its name
    kind: build
    build:
      bundle:
        path: dist/portal
        manifest: deploy/portal/ankra-release.yaml
  - name: build-portal-image    # container image for Kubernetes, attributed explicitly
    kind: build
    build:
      component: portal
      dockerfile: portal/Dockerfile
      context: portal
  - name: build-node-agent      # release bundle that belongs to no component
    kind: build
    build:
      bundle:
        path: dist/node-agent
        manifest: deploy/node-agent/ankra-release.yaml

​

Monorepo: PR-only checks, full builds on push

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

stages:
  - name: checkout
    kind: checkout
  - name: test-web
    kind: run
    image: node:22
    run: pnpm -C web test
    needs: [checkout]
    when:
      pull_request:
        paths: ["web/**", "packages/ui/**", ".ankra/**"]
      push: {}
  - name: test-api
    kind: run
    image: golang:1.26
    run: go test ./...
    working_directory: api
    needs: [checkout]
    when:
      pull_request:
        paths: ["api/**", "go.work", ".ankra/**"]
      push: {}
  - name: report
    kind: run
    image: alpine:3
    run: ./scripts/summarise.sh
    needs: [test-web, test-api]
    if: always()

• A pull request’s changed files are read from your provider when the run is triggered, up to 300 paths. When they cannot be read, or the change is larger than that, no stage is skipped for its paths, and the run’s paths_unverified says why.
• A stage that needs a component stage keeps the usual rule: it is skipped when that stage is left out. To run it anyway, name the stage in skippable_needs, so it waits on what the skipped stage waited on, or give it an if: with a status function such as always() (above), so its condition decides and needs.test-api.result reads skipped.
• Check the shape before you commit it. ankra pipeline validate --changed-file web/app.ts prints each stage against push and pull request, so you can see the plan for that change.
• Write each list once. When several stages share a list, or every list carries .ankra/**, name it under path_sets: and write {set: <name>} where the list was, for example path_sets: {pipeline: [".ankra/**"], web: ["web/**", "packages/ui/**", {set: pipeline}]} and paths: [{set: web}].

​

Affected-only stages: skip what a change did not touch

stages:
  - name: checkout
    kind: checkout
  - name: test-web
    kind: run
    image: node:24
    run: pnpm -C web test
    needs: [checkout]
    paths: ["web/**", "packages/ui/**", ".ankra/**"]
  - name: test-api
    kind: run
    image: golang:1.26
    run: go test ./...
    working_directory: api
    needs: [checkout]
    paths: ["api/**", "go.work", ".ankra/**"]
  - name: build
    kind: build
    needs: [test-web, test-api]
    build:
      dockerfile: Dockerfile
  - name: scan
    kind: scan
    needs: [build]
    scan:
      scanners: [semgrep, trivy]
  - name: gate
    kind: gate
    needs: [scan]
    gate:
      require_stages: [scan]
  - name: publish
    kind: publish
    needs: [gate]
    with:
      image: registry.example.com/acme/shop
    when:
      events: [push]

• paths: or when.paths. when.paths skips the stages behind a stage it leaves out, so a filtered test stops the publish behind it; that is the right rule for a component’s whole chain (its build, scan, gate and publish skipped together), and it is what the generated monorepo pipeline uses. paths: is for a stage whose absence should not hold anything back. One stage declares one of them, never both.
• Every event. paths: applies to pushes as well as pull requests, so a push to main also runs only the affected tests. For “pull requests check what they touch, pushes check everything”, use the event-scoped when recipe with skippable_needs.
• What it refuses. A stage that is left out produced nothing, so ankra pipeline validate refuses (pipeline_paths:) a stage that reads its outputs, a build that another stage needs (what needs a build reads its image), a checkout, gate or approval with paths:, and a scan a gate names in require_stages. It warns about an affected-only scan (a change outside its paths is not scanned) and an affected-only deploy, publish or preview that another stage needs.
• When the change cannot be seen (no change list, or more than 300 files), no stage is left out, and the run’s paths_unverified says why.
• Check a change before you commit it: ankra pipeline validate --changed-file web/app.ts prints which stages run and which are skipped.

​

Affected from the dependency graph: affected:

stages:
  - name: checkout
    kind: checkout
  - name: test-api
    kind: run
    image: golang:1.26
    run: go test ./...
    working_directory: api
    needs: [checkout]
    affected:
      go: ["./..."]
    paths: ["migrations/**"]
  - name: test-web
    kind: run
    image: node:24
    run: corepack enable && pnpm install --frozen-lockfile && pnpm --filter @acme/web... test
    needs: [checkout]
    affected:
      pnpm: ["@acme/web"]
  - name: build
    kind: build
    needs: [test-api, test-web]
    build:
      dockerfile: Dockerfile

• go names Go packages the way the stage’s own go test does: ./... and ./internal/api are read from the stage’s working_directory, and an import path such as example.com/shop/libs/... works too. Ankra reads every go.mod in the repository, so a module another one pulls in through a local replace directive counts. A change to go.mod, go.sum or vendor/ reaches every package of that module.
• pnpm names workspace packages by name (@acme/web) or by directory (./apps/web). A dependency on another workspace package, by name, workspace: alias or file: path, is followed. A change to a file at the repository root, such as pnpm-lock.yaml, the root package.json or pnpm-workspace.yaml, or to a pnpm patch (any file under patches/ and any .patch file), reaches every pnpm stage. Documentation and Go files at the root do not: *.md, LICENSE, CHANGELOG, .gitignore, .gitattributes, *.go, go.mod, go.sum, go.work and go.work.sum.
• paths: beside affected: adds files no import graph sees: migrations, fixtures a test opens by path, a script the stage runs. A matching file runs the stage.
• Where the graph comes from. The run’s checkout step reads the graph of the exact commit it checked out, in a few seconds, and records an answer for each stage. Nothing is cached and there is no extra step. The planner decides only what it can without the code: a change list it could not read in full, a change to .ankra/pipeline.yaml or a matching paths: glob runs the stage, and a change of no files leaves it out.
• A skip needs an answer. The stage is skipped only when the checkout answered that no changed file reaches it. No answer at all (a pattern that names nothing, an analysis that failed or took over two minutes) runs it, and the checkout’s log says why. A pipeline with no checkout stage never reads the graph: its affected: stages run on every change, ankra pipeline validate warns about it (pipeline_paths:), and the run’s plan records it (plan_paths:).
• A skip never waits for capacity. A not-affected stage is concluded as soon as the checkout has answered, without waiting for a free CI slot on a busy cluster, and the stages that need it start as soon as they have one of their own. The time it saved is recorded with reason not_affected.
• Promotion. A merge that promotes the pull request run’s image counts a stage that run skipped as not affected, when the merge changes no file that run’s graph was not asked about. Otherwise the merge builds in full and reads the graph itself.
• The same rules as paths:. affected: makes a stage affected-only, so it is refused where a skip would be unsafe: a stage whose outputs another reads, a build another stage needs, a checkout, gate or approval, a scan a gate judges. A false if: is still the condition’s own skip and skips what needs the stage.
• Check a change before you commit it: inside your checkout, ankra pipeline validate --changed-file libs/auth/token.go reads the same graph from your working tree and shows which stages the change reaches.

​

Newest commit wins

concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true

• ankra pipeline validate (and ankra application pipeline validate) reports pipeline_concurrency_queues_behind: at severity advice, naming the group and the one line that changes it. Advice never blocks a run and never fails the command.
• A queued run whose Waiting: line names an older run of the same branch or pull request that will not be superseded carries the same recommendation. A holder on another branch does not - that is the group serialising across branches, which is what a group is for.
• A pipeline converted from a GitHub Actions workflow keeps the workflow’s own queue-behind behaviour, with a conversion note recommending the flag for a per-branch group on a pull_request trigger.

​

What a pull request gets

​

The review reads your pipeline, not just GitHub Actions

• the failing step’s name, kind and error message, when the run is failing - not its log, which stays behind ankra pipeline logs
• the run’s scan findings, by tool and severity, with the highest-severity individual findings named
• the gate step’s own verdict and blocking count, once one has concluded
• the build step’s reported image digest, once one has concluded
• the authority sentence, when the run executed under anything other than the plainly approved definition

​

A human can say “merge when green”

• the requester is an active member of your Ankra organisation holding pipelines.operate, and the binding’s AI mode is Agent - in Ask mode the request is refused, naming the setting to change
• the GitHub login that commented is linked to that member through an OAuth-verified identity. A login claimed by hand, or auto-filled from an Auth0 GitHub sign-in, proves the account exists and not that the commenter owns it, so it no longer counts as verified; the refusal says to link GitHub again. A service principal is refused outright - merging is a human act
• the requester still holds pipelines.operate, is still an active member and is still OAuth-verified when the sweep actually merges, not only when the comment was written. A request can wait up to 24 hours, and an administrator can revoke the permission inside that window
• the pull request’s head is not a fork
• the newest pipeline 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 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, this one is not scoped to the current commit, so a changes-requested left on an earlier push still blocks until the same reviewer clears it with a later review

​

The merge train: test every pull request as it will merge

ankra pipeline train enable --application orders-api            # pipelines.manage; --max-cars 3 to test three at once
ankra pipeline train add 412 --application orders-api           # pipelines.operate; --head-sha pins the commit you reviewed
ankra pipeline train list --application orders-api              # the train in order, and what recently left it
ankra pipeline train remove <entry-id> --application orders-api

• A car fails. The pull request leaves the train with the failing run linked; every car behind it, which included it, is rebuilt without it. Each car tests everything ahead of it, so the pull request that failed is the one that broke, with no bisection.
• Somebody merges around the train. Every car built on the old base branch head is rebuilt on the new one, and nothing is merged onto a base its car did not test.
• The pull request is pushed to, retargeted or closed. It leaves the train: the train merges the head a person put in it, never one that arrived later.
• GitHub declines the merge - usually because the pull request’s own required check is still running. The car waits, passed, and the merge is retried every pass; after three hours it leaves the train with GitHub’s reason.
• A fork. Refused, as for merge when green.

​

Chat watches a run, and a failed build gets a fix

​

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 delivers as a one-time, per-step reveal - never written into a job spec or a log - 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 - enforced end to end today: a publish step refuses by name when its run has no successful gate step immediately upstream, and it re-tags only the exact digest that gate evaluated.
• 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 a backup vault - the organisation’s own, or the Ankra-managed default one - 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, the image gate) and its pipeline policy (the authority ceiling an administrator sets). The image gate is no longer only a setting: gate steps (below) evaluate every run against it.
• Connecting a repository, with an optional link to an application and a CI-cluster override, and disconnecting one. POST /org/pipelines/repositories connects a bare repository and, on GitHub, reads its committed .ankra/pipeline.yaml as the definition of record in the same call; DELETE /org/pipelines/repositories/{id} disconnects it, 409 while a run is still live. An Ankra Application connects and decides its own repository automatically on create and on every reconcile. A new application’s setup pull request commits .ankra/pipeline.yaml by default instead of a generated workflow.
• Migrating an existing application onto a pipeline with one call - see Migrate an existing application.
• 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. A Bitbucket Cloud push that updates several branches or tags at once starts each branch’s and each tag’s pipelines, and a Bitbucket pull request’s abbreviated head commit is resolved to the full commit through the repository’s credential before its run is created; a head that cannot be resolved starts no run. A private GitLab repository builds through the organisation’s stored source credential the same way GitHub and Bitbucket Cloud ones do, and a GitLab project under a nested group (group/subgroup/project) resolves to a clone URL instead of being refused by the owner grammar.
• A stage kind nothing can run is skipped, not left pending. The kinds this build has no executor for - preview, agent, approval, webhook, automation, ankra, external and verify - now report a validation warning naming the stage, its kind and the wave that ships its executor (severity warn, so the pipeline still plans and every other stage still runs), and the planner skips exactly those stages with reason kind_unavailable. A run that declares one concludes on its own; before this it sat pending forever, holding its concurrency group with it. A pending step whose run has outlived the sum of every step’s timeout is additionally reaped as infra_error / step_stranded, so a step that stranded for a reason no static check can see - a cluster that never resolved, an agent that never advertised support - cannot pin a run open either.
• uses: is refused by name, at validate time. Any uses: reference - ankra/*, custom_tool/* or repo:<owner>/<name>@<ref>#<path>, however it is spelled - is fatal with one sentence, “Reusable steps are not available yet; write the step as run:”, until the step library ships. That is deliberately louder than the old behaviour, where a uses: stage validated and then failed at dispatch with an error that read as “you forgot to write a script”.
• Step outputs and deferred conditions are resolved at dispatch. A stage’s if: that depends on a step’s result, and every ${{ steps.<key>.outputs.<name> }} or needs.<stage>.* reference in run, env, with, image, working_directory and outputs:, are evaluated once the steps they wait on have concluded - a false condition concludes the step skipped before any secret is revealed, and a reference dispatch cannot resolve concludes it infra_error naming the field rather than passing a literal ${{ }} into a script.
• on_failure and finally stages run when their names say. An on_failure stage runs after the main stages have all concluded and only when one of them failed; after a green run it is skipped with its reason. A finally stage runs after everything before it has concluded, whatever the outcome, and also after a run that had started is cancelled (ankra pipeline cancel --force skips it). See Failure and cleanup stages for the exact rules.
• In-cluster execution of checkout and run stages on the organisation’s CI cluster: a hardened Job per step in ankra-ci, a per-run workspace volume, cache volumes, service sidecars, network tiers, resource ceilings, timeouts, live logs, and one automatic retry of Ankra’s own failures. checkout clones with a pinned public git image, a shallow fetch of the exact commit with a fallback to fetching its ref, and refuses an lfs: request by name rather than silently checking out pointer files.
• Caches survive between runs, inside their own trust scope. A stage’s cache: block resolves to the same PersistentVolumeClaim on every run that declares the same key, scoped to the repository, cluster, cache path and the trust of the run resolving it - the second run’s test stage mounts what the first run’s left behind, not an empty volume. A miss on the exact key that matches a restore_keys prefix restores the most recently used claim under that prefix instead of starting cold, the same semantics as GitHub Actions’ own cache action, and that prefix search stays inside the caller’s own scope too. Retention is unchanged by any of this: a claim nothing has resolved to for ci_cache_retention_days (below) is still deleted by the same sweep, per claim.
• A fork’s run resolves no shared cache at all, and a branch never resolves the default branch’s. Two holes, closed together. A pull request from a fork that runs restricted - the ordinary fork_policy: read_only case - is refused a shared cache at dispatch, on the same predicate that already withholds its secrets and credentials: every declared cache degrades to the pod-lifetime volume a cluster with no usable StorageClass already gets, and the step’s execution metadata carries pipeline_caches: "caches are not shared with fork runs" so an operator can see why the build was cold rather than guessing. Such a step never reaches the cache store at all. Separately, every claim now carries a trust scope: default_branch for a run on the repository’s own recorded default branch, branch for everything else - a feature branch push, a pull request (fork or not), a tag, a manual dispatch of a non-default ref. The two scopes never share a claim, and neither an exact-key hit nor a restore_keys prefix match crosses between them, so a less-trusted ref can no longer poison what a production build restores. It is deliberately coarser than per-branch isolation: the threat is an untrusted ref writing into what a trusted one reads, not one feature branch reading another’s warm cache. Claims that existed before this deploy were backfilled into branch, the untrusted scope - nothing on a row records which run wrote it, so the true value cannot be recovered, and defaulting the other way would have carried the hole forward for every cache written before the fix. The cost is one cold build per cache key on your default branch, once.
• A restricted fork run is budgeted, not only restricted. It is clamped to at most 8 matrix legs per stage, a 60-minute timeout per step, 2 CPU and 4Gi of memory per step, no sidecar services, no cache volumes and 256 MiB of artifacts and logs across the whole run - fractions of the platform-wide ceilings of 64 legs, 6 hours, 8 cores, 32 GiB and 2 GiB, because a drive-by pull request triggers this with nobody having reviewed it first. Matrix legs, timeout, compute and sidecars are clamped in the planner, so the plan ankra pipeline validate, the dry run and the pull request’s status comment render is the run that actually executes, rather than one silently rendered smaller at dispatch; caches are refused at dispatch, and the artifact budget bounds what the run is granted, from the sizes its steps declare. The matching ceiling on what actually arrived - the one number a step cannot lie about - is written into the artifact store but has no settle lane calling it yet, so today the budget is enforced on the grant rather than on the upload. A plan_fork_budget: diagnostic states the ceilings once per run, plus one more for each stage that actually hit one, and a declared quantity the planner cannot read is clamped rather than given the benefit of the doubt. An organisation’s own policy may lower these numbers further; nothing raises them for a fork.
• build produces a real digest. A rootless BuildKit pod in its own ankra-ci-build namespace resolves its own builder, source and push target at dispatch and pushes the image it builds, by digest, to the organisation’s CI staging repository; a bare repository with no application link, or a component with no resolvable registry, gets a named refusal instead of a guess. provenance: true and sbom: true ask BuildKit to attest the digest it pushes.
• Ankra platform builders build when your cluster cannot. When the CI cluster cannot build, the organisation set ci_build_fallback: platform_builders, and Ankra has granted the organisation platform builds, a build step runs on Ankra platform builders instead - the same staging-repository push and the same scan/gate/publish downstream, with the step’s executor recorded as whichever lane actually ran it. What “cannot build” covers, how to confirm and request the grant, and what a fallback build looks like from your side are all in Ankra platform builders below. An application that publishes to a registry you operate yourself is pushed by this lane with the push robot Ankra minted for it there, exactly as the in-cluster build is.
• scan runs three tools for real, one step per tool. Trivy (filesystem, a CycloneDX SBOM, and - once a build produced one - the image itself), Semgrep and Checkov, each from a pinned, digest-referenced public image the organisation’s own ci_allowed_image_prefixes cannot turn off, writing the reports gate and the application’s Security tab both read. with.semgrep_config names the registry packs to run (p/default p/docker …); undeclared, Semgrep runs its own --config=auto.
• gate judges what scan found, and scan.fail_on is part of the judgement. It reads the run’s own persisted findings against the organisation’s ci_image_gate policy (below), which a gate stage’s own with: may only tighten, never loosen; a declared scanner that recorded nothing fails the gate by name rather than passing as clean. Each required scan stage’s own fail_on is folded in on top, per scanner and tighten-only: a pull request head may add scrutiny to its own pipeline, never remove the organisation’s. A fail_on value that is not that scanner’s own severity vocabulary at all - Checkov’s none, a Trivy image-gate word such as app - carries no floor rather than the loosest one.
• publish re-tags only the digest gate approved, and proves it. A publish step refuses by name when its run has no successful gate step; otherwise it re-tags the exact digest build pushed to staging as sha-<7> in the application’s real repository - never rebuilt, never a different digest than the one scan and gate judged. The gate now records the digest it actually judged on its own step outputs, and publish refuses when the build’s digest is anything else - including when the gate recorded none at all, because “no record” is unknown, not agreement. Before this the guarantee rested on ordering alone: a successful gate existed upstream, so surely it had judged this image.
• deploy rolls a release out to your own hosts. A kind: deploy stage releases the signed release bundle a publish stage of the same run produced to the active host targets of its environment: machines outside Kubernetes that run ankra-host-agent and connect outbound only (see ankra targets). The platform settles the step from what each host reports, and ankra deployments shows how every host fared. The stage’s environment and deploy block are protected, a pull request or fork run never deploys (deploy_untrusted_event), and the step refuses an artifact this run did not publish. It does not deploy to a Kubernetes cluster: an application’s own push to deploy does that. See the deploy row of the reference.
• A monorepo’s components are tracked separately. A publish step resolves the build and gate steps carrying its own stage suffix rather than whichever succeeded first, so publish-web can no longer re-tag api’s digest into web’s repository, and a stage name following neither convention is refused by name instead of guessed at. A scan stage honours working_directory, so a component’s scan reads the tree its build and test stages do rather than the whole checkout. Build observation is recorded per component, with only the primary component also moving the application-level record, so push-to-deploy, previews and rollback keep converging on the image they always did.
• A run plans from .ankra/pipeline.yaml at its own commit (GitHub). The planner fetches the file at the run’s head sha and plans the run’s logic from it, records which source won (definition_source: head_file, stored or default), and falls back to the stored definition with a diagnostic when GitHub is briefly unreachable - a transient read failure must never stop a push running its own pipeline. Only a head file that really was fetched and is then unparseable or fatally invalid refuses the run. Protected authority is unaffected: it still resolves from the default branch’s approved definition, never from the head file. A re-run re-plans from the original run’s definition, so re-running an old run reproduces it rather than silently executing whatever the pipeline has become since.
• Previews deploy the pipeline’s own digest. An application whose pipeline source is ankra_pipeline gets its pull-request preview from the build step’s own digest for that head - by digest, never a mutable tag - on GitHub, GitLab and Bitbucket Cloud alike; the gateway also re-drives a stalled preview the moment a pipeline run concludes, on top of the existing poll fallback.
• Fork pull requests run, restricted. checkout and build clone the fork’s own head anonymously - never the pipeline’s own repository - build renders with no push target so nothing it produces can reach a registry, and every stage but checkout, build and scan runs with no network at all regardless of what the fork’s own copy of the definition asks for. Such a run also resolves no shared cache and is held to fixed matrix, timeout, compute and artifact budgets (above). See Forks.
• Secrets and credentials delivered into steps as one-time, per-step reveal grants collected by the agent at step start: a secrets binding sourced app_env_secret, org_variable or registry resolves, and a credentials binding sourced git or registry resolves; secrets: [{from: credential}] validates but is not deliverable yet, and cloud and object_storage credentials are refused by name until the run gets its own scoped identity (below).
• Schedules fire. The cron trigger dispatches through the same trigger every push and pull request uses, advancing from a stored watermark so a loop that was down for a while does not replay every occurrence it missed.
• Protected authority is enforced, not only modelled. Whichever definition supplied a run’s logic, its authority resolves from the default branch’s admin-approved definition; a pull request that changes a protected section (below) executes under the last approved authority instead, and the check run, commit status, the definition response and the pull request’s own status comment all say so. The last-approved fallback only ever offers a definition that was itself, at some point, the default branch’s own head - proved from the repository’s run history, never from the approval columns on the definition row alone.
• One approval route, whichever id you hold. The application-addressed approval (POST /org/applications/{id}/pipeline/approve-definition) is now an alias for the definition-addressed one, so both run the same checks - a human actor rather than a service principal, the definition must be the repository’s current default-branch definition, a second approval of an already-approved definition is a conflict rather than a silent yes - and both write the same audit row. Before this the application-addressed route had none of them: a caller holding that application’s pipelines.manage could approve any definition row belonging to its repository, including one sourced from a pull request head that never was, and might never be, the default branch’s own content.
• A dispatch proves its commit belongs to the repository. POST …/pipeline-runs resolves the ref it was given - or the repository’s default branch - through the repository’s own host before anything is written, and accepts a caller-supplied head_sha only when it is that reference’s current tip or, on GitHub, a provable ancestor of it through a compare read. Anything else is refused by name, and so is a transport failure that leaves the question unanswered: an unanswerable question is not a yes. GitLab and Bitbucket Cloud have no compare read, so a commit named there is held to the exact tip. Re-runs keep working and are deliberately exempt - a re-run’s commit is one Ankra itself recorded when the original run was created, not a claim arriving with this call, which is what lets a fork pull request’s run be repeated at all.
• A dispatch’s own definition is what actually runs. --spec-file (spec_yaml on the API) is persisted verbatim on the run, and both the planner and the dispatcher render every step from it, instead of shaping the plan and then silently re-rendering each step from the stored definition. Only the logic moves: an override is content nobody committed, so its protected sections are compared against the default branch’s approved authority exactly as a pull request head’s are.
• Five more sections are protected authority. services, cache, resources.cpu and resources.memory, timeout and a stage’s with: block now hash, resolve in both directions and surface by name, so a head can no longer ask for far more compute than the organisation meant to grant, remove its own or the trusted definition’s timeout, change which run’s output a cache restores into the workspace, or rewrite a gate stage’s own scan-tool configuration. This moves every definition’s protected hash - see the re-approval note under Logic is open, authority is closed.
• A sidecar is held to the step’s own boundary. A named services: entry’s image goes through the organisation’s image policy and its env through the reserved-name check, both as a refusal of the whole step rather than a diagnostic that runs it anyway; ankra pipeline validate names the same violation at services[<name>].image. A sidecar could previously pull any image and set ANKRA_*, the loader and PATH variables, or the image builder’s own BUILDCTL, BUILDKIT_HOST and DOCKER_CONFIG.
• Two organisation ceilings that nothing could set now bite. ci_ignore_unfixed (below) is an organisation-wide floor a gate stage’s own with: may only tighten, and max_cache_size on the pipeline policy is stored and enforced - every declared cache had been held to it since the ceiling was written, with nothing able to set it, so every organisation silently resolved “no ceiling”.
• egress-https reaches the public internet, and nothing private. The tier’s 443 rule now excludes RFC1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), the whole of link-local 169.254.0.0/16 rather than only the 169.254.169.254 endpoint that used to be its single exception (AWS ECS serves task metadata at 169.254.170.2), and carrier-grade NAT 100.64.0.0/10 (Alibaba Cloud answers at 100.100.100.200, inside it). There is an IPv6 rule at all now, excluding fd00::/8, fe80::/10 and AWS’s fd00:ec2::254. DNS stopped being “port 53 to any pod in the cluster”: it is the kube-system namespace plus 169.254.0.0/16 for a cluster running NodeLocal DNSCache, and the services tier - which carried no DNS rule at all - gained the same one. This breaks a pipeline that reaches a private HTTPS endpoint, and the symptom is a connection timeout rather than a refusal, so name the range in ci_egress_allowed_cidrs (below) before the step runs: a build that pushes to a registry on a private address - an in-cluster registry, a Harbor inside your VPC - cannot reach it until that entry exists. The agent renders a step’s NetworkPolicy itself, so the tightened tier arrives with the agent release of 5 September 2026; a cluster still on an older agent keeps the previous tier until the fleet roll reaches it.
• An image policy prefix ending in a separator means that separator. An entry ending in /, : or @ used to match nothing at all, because the matcher requires one of those three characters after the prefix - the boundary check that stops ghcr.io/my-org admitting ghcr.io/my-org-evil/api. Each now admits exactly its own boundary: ghcr.io/my-org/ admits ghcr.io/my-org/api and refuses ghcr.io/my-org and ghcr.io/my-org:v1, ghcr.io/my-org: admits a tag and not a path, ghcr.io/my-org@ admits a digest, and registry.example.com/ admits paths on that host and never registry.example.com:5000/anything, which is a different endpoint. Trimming the separator away would have widened each of those rather than narrowing it, so that is not what happens, and an entry that is only separators - or ends in two of them - matches nothing rather than becoming the empty prefix every image starts with. The settings API refuses a trailing separator at write time and always has, so a stored ci_allowed_image_prefixes cannot carry one: this is defence in depth for the prefixes Ankra sets in code and for the copy of the policy a step’s payload carries, not a change to what an administrator can store.
• 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 - on a pull request - the same run state and authority sentence in the pipeline section of Ankra’s one status comment.
• The AI review reads your pipeline, and a human can say “merge when green”. See What a pull request gets above: a bounded pipeline-facts block in the review prompt, a merge when green pull request comment gated on the run, its gate, both reviews and its authority, and a watch_pipeline_run chat tool whose unattended fix loop reacts to a failed build step.
• Step logs and declared artifacts stored in the organisation’s oldest ready backup vault - or, for an organisation with none, in the Ankra-managed default vault - listed and downloaded through the API today; ankra pipeline artifacts and artifacts download speak the same routes and read the same way from the CLI’s next release (see Commands and API). A vault is no longer something to arrange first - a scan stage’s reports travel the same path, so a fresh organisation records findings and passes its gate without provisioning a bucket; bringing your own decides where the objects live, not whether they are kept (see Before your first run).
• Long runs stay alive. Every settle pass re-stamps the run’s heartbeat, so the platform’s twenty-minute stale-run reaper no longer fails a pipeline that is still working. A run whose steps genuinely stopped reporting is still reaped, and the reason is recorded.
• Run history is retained by policy, not forever. ci_run_retention_days (default 90, 7 to 365, below) bounds how long a concluded run is kept, and an hourly sweep deletes past the window in batches. It never deletes a live run, never a repository’s own newest concluded run, and never a run still carrying an artifact the artifact reaper has yet to remove from the vault.
• Run outcomes reach your destinations. pipeline_run_failed, pipeline_run_succeeded, image_gate_blocked, preview_ready and preview_failed are notification kinds like any other, produced once per run (or once per gate verdict, or when the preview row itself flips), so notification routing sends them to Slack, Teams, PagerDuty or a webhook alongside everything else Ankra reports.
• A truncated log says so, and the failing step names its own error. The agent reports how many log lines it had to drop to backpressure; that count is recorded on the step and shown as a notice under its row on both the check run and the pull request status comment, so a step whose output was silently cut no longer looks like one whose log arrived whole. The check run’s step table also carries the failing step’s own error message (truncated to 200 characters) in its Outcome cell, instead of only the run’s error in one blockquote at the end.
• The portal. The application’s Pipelines section shows Ankra pipeline runs with a timeline and an in-app log viewer beside the GitHub Actions view; organisation Settings → Pipelines lists connected repositories; the application’s Security section reads a pipeline’s own findings once a run has concluded for its repository, falling back to the GitHub-artifact reader until one has.

• The runner for verify. No runner image exists, so a probe, smoke, load_test, assert_promql or restore_verify sub-block never runs. The stage is skipped with kind_unavailable rather than dispatched into an image pull that cannot succeed, so it no longer holds the run open - but it also verifies nothing, and a pipeline that relies on it is not being verified.
• The executors for the remaining stage kinds - preview (a per-pull-request environment deployed from inside the pipeline DAG, not to be confused with an Application’s own pull-request preview, which already deploys a pipeline’s digest, above), agent, approval, webhook, automation, ankra and external. Each validates with a warning and is skipped, so a run containing one concludes; none of them does the work its name promises. In particular an approval stage does not block a run on a human today - it is skipped, and everything downstream of it runs.
• The per-run identity permissions mints, so a step can call the ankra CLI with exactly the authority the default branch granted - a converted github.token reference already diagnoses itself as “the run-scoped ANKRA_TOKEN”, naming what does not exist yet rather than resolving to nothing; cloud and object_storage credentials wait on the same identity.
• The built-in ankra/* step library behind uses:, organisation step templates, and custom_tool/<name> steps. Until it ships, any uses: is fatal at validate time with one sentence telling you to write the step as run:.
• Nothing pins the step keys an expression names. ${{ steps.<key>.outputs.<name> }} resolves at dispatch against the run’s real steps, but a key that does not exist - a typo, or a matrix leg the writer guessed at - interpolates to empty text rather than being refused. The validator declares expression roots, not key sets, and a step key is a matrix-expansion product it cannot know; closing this belongs in the planner, which does know the expanded keys.
• The user-declared retry block is validated and carried to the agent, not applied. A step’s own retry: is parsed and stored on the plan, but nothing dispatches a second attempt from it - only Ankra’s own infrastructure failure classes retry automatically (see When something fails); a script that exits non-zero is final today regardless of retry.max_attempts. Dynamic matrices (matrix: ${{ fromJSON(steps.plan.outputs.legs) }}, fanning out over a previous step’s own output) are not available either - every axis must be written out in the file.
• Attestations and SBOM referrers on the image you actually deploy. build’s provenance/sbom flags attest the digest it pushes to the CI staging repository; publish’s re-tag copies that one image manifest, not the attestation manifests beside it, so they are not on the digest your application deploys. Trivy’s SBOM is an artifact in the vault today, not an OCI referrer on any image.
• Merge-when-green and automatic disposition re-evaluation are GitHub only. A GitLab or Bitbucket Cloud merge when green request is accepted and then refused, because neither provider adapter reports the capability to merge yet; a push to a GitLab or Bitbucket Cloud default branch that adds or removes .ankra/pipeline.yaml answers insufficient evidence rather than re-evaluating the application’s pipeline source, because the raw-file read that evaluation needs has no GitLab or Bitbucket equivalent wired in yet.
• A dedicated log stream for pipeline output, on the agent side. The platform half is in place: the pipeline_output JetStream stream exists with its own capacity and retention, the agent is granted publish on its own cluster’s subject, dispatch renders that subject onto every step, and the log relay reads the dedicated stream first and falls back to the shared one. What has not shipped is the agent release that actually publishes there, so live output still rides the platform-wide execution_output stream until your cluster’s agent is upgraded to a release carrying that change. Nothing about ankra pipeline logs or the check run changes when it does - the relay already reads either.
• Planning from the committed file is GitHub-only. A GitLab or Bitbucket Cloud run plans from the stored definition permanently, because the bounded raw-file read the planner uses has no equivalent wired in for those providers yet; the run records definition_source: stored and says so in a diagnostic rather than pretending it read your commit.
• Annotations and metrics. A step’s stdout can already carry $ANKRA_OUTPUT key=value lines, read back onto the step; the equivalent for check-run annotations (::ankra::notice file=…,line=…::msg) and custom metrics (::ankra::metric name=…,value=…) is not ingested anywhere yet. Test reports are: see Test results.
• Environments hydrated from restore points, verification stages, promotions with approvals, and canary rollouts - see What comes next.

​

Test results

  - name: "e2e"
    kind: "run"
    run: "pnpm test:e2e"
    artifacts:
      - name: "junit"
        paths:
          - "reports/junit"
    test_results:
      - format: "junit"
        path: "reports/junit"        # a file, or a directory of report files

• The run page’s Tests section: failed tests first, then flaky ones, then the slowest, each with its duration, attempts and failure message. A report that was declared but not uploaded or could not be read is listed with the reason.
• GET …/pipeline-runs/{run_id}/tests: the same summary over the API.
• GET …/pipeline-tests/history?test_key=…: one test’s outcomes in the newest runs of your default branch (or branch=), with its flaky rate.
• GET …/pipeline-tests/timings?stage=…&group_by=file|test: each file’s or test’s mean recorded duration on the default branch, to balance shards by time. runs_sampled: 0 means there is no data yet; fall back to an even split.

​

Quarantining a flaky test

1. It is a kind: run step that failed on its own (step_failed). A timeout, an infrastructure error, a refusal, and any build, scan, publish, deploy or verify step always fail as before.
2. Quarantine is on for the repository.
3. The step declared at least one test report, and every one was uploaded and read whole.
4. The reports hold at least one failed test, and every failed test is quarantined. A test that passed on a retry counts as flaky, not failed.

ankra pipeline tests quarantine settings --enable           # turn it on for this repository
ankra pipeline tests quarantine candidates                  # the tests that qualify now
ankra pipeline tests quarantine add <test key> --reason "flaky since the cache change, ENG-123"
ankra pipeline tests quarantine                             # settings, quarantined and recently released tests
ankra pipeline tests quarantine release <quarantine id or test key> --reason "fixed in #42"

​

Organisation CI settings

curl -X PUT https://platform.ankra.app/api/v1/org/ci-settings \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"ci_egress_allowed_cidrs": ["10.42.0.0/16", "192.168.10.0/24"]}'

​

Capacity and concurrency

​

Why a run is waiting

​

Seeing and raising capacity

• Runs queue as waiting_on_run_cap. ankra org ci-settings set --max-parallel-runs N (up to 64).
• Runs queue as waiting_on_ci_slots. ankra cluster agent ci set --workers N --cluster <name> (up to 128 on current agents).
• Steps are slow to start although slots are free. The cluster has no room for the pods: raise the node group’s autoscaling maximum (ankra cluster node-group autoscaling get shows it), or use larger nodes. More slots without more nodes only means more steps waiting for a node.

​

Step placement

ankra cluster agent ci set --cluster so-upcloud-infrastructure --node-group pipelines

ankra cluster agent ci set --node-selector pool=ci --toleration dedicated=ci:NoSchedule

​

Ankra platform builders

• The cluster’s agent does not run pipeline steps. It predates the capability, or no agent has checked in at all. Every stage of the run is affected; build is the one kind that has somewhere else to go.
• The cluster’s node runtime confines the rootless image builder. Typical for AppArmor on k3s or Ubuntu nodes, and for a kubelet that defaults seccomp to RuntimeDefault. Every other stage runs in-cluster as normal and only build is routed away; build_runtime_confined has the mechanics.

• In a multi-component (monorepo) application, a build stage must belong to a component the application records: either it declares build.component, or it is called build-<component> (which component a build belongs to). A stage that does neither, or that declares a component the application does not record (a typo, or a component renamed since the run was planned), is refused as platform_build_unavailable, and the message lists the components the application knows. A single-component application’s build stage may be called anything. A repository with no linked application is refused the same way, because it has nowhere to push whoever builds it.
• Every build_args entry must carry a literal value, written NAME=value. In-cluster, a bare NAME lets BuildKit read the argument from the build pod’s own environment; the platform builder has no such environment, so a bare entry is refused as build_fallback_unsupported rather than built silently without the argument.

​

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 the whole of resources: gpu, cpu and memory, so a head cannot ask for far more compute than the organisation meant to grant.
• A stage’s timeout, so a head cannot remove its own or the trusted definition’s and let a step run far past what was approved.
• A stage’s cache block - key, paths, size, restore_keys and fallback - which decides whose earlier output is restored into this run’s workspace.
• A stage’s with: block, which is where a gate stage’s own scan-tool configuration lives.
• The services block - each sidecar’s image, environment and ports.
• 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.

• approved - the head declares exactly the trusted authority. An ordinary pull request that changed no protected section reads this way.
• unapproved - a push to the default branch itself changed a protected section nobody has approved yet; the run executes under the last approved authority (or none) until an administrator does.
• changed_on_head - a pull request added a credential, widened its egress, or moved a step onto another node pool. The change is ignored for this run and surfaced, never silently granted because a commit landed.

curl -X POST https://platform.ankra.app/api/v1/org/pipelines/definitions/<definition-id>/approve \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"

​

What a step runs as

• /workspace is the run’s shared volume: the checkout lands there, and it carries files from one step to the next. Anything large belongs here.
• /tmp is a 256 MiB memory-backed tmpfs, private to the step’s pod and empty again at the next step. It counts against the step’s memory, and a compiler or linker that stages intermediate files in /tmp runs out of space long before the workspace would. Point TMPDIR into the workspace for anything that writes big temporary files, with export TMPDIR=/workspace/.tmp && mkdir -p "$TMPDIR" at the top of the step’s run script.
• /dev/shm is 64 MiB unless the stage sets shm_size.

• Network tiers. none denies all egress, and is what a stage gets when neither it nor the pipeline’s defaults names a tier - except for checkout, build and scan, whose only job is outside the cluster and which default to egress-https instead (the tier a stage gets by default). egress-https permits 53/UDP and 53/TCP to the cluster’s own DNS - the kube-system namespace, plus 169.254.0.0/16 for a cluster running NodeLocal DNSCache - and 443/TCP to public addresses only: RFC1918, 169.254.0.0/16, 100.64.0.0/10, fd00::/8, fe80::/10 and AWS’s fd00:ec2::254 are all excluded, so a step on it reaches neither your private networks nor any cloud metadata endpoint that hands out the node’s identity. A checkout, build or scan stage that explicitly declares network: "none" is honoured rather than widened back - the tier is clamped only on a restricted fork run (below) - but the validator warns what that stage loses, because a step with no way to reach its source, its base images or its vulnerability database is not one broken step, it is a pipeline that cannot run at all. services is deny-all plus the run’s own pods and that same DNS rule; the sidecars a step declares are containers in its own pod, reached over loopback by name. A private destination a pipeline legitimately needs is named in ci_egress_allowed_cidrs, which renders as an extra peer on the 443 rule of the egress-https tier alone, is re-validated when the step is rendered rather than trusted from the settings row (an entry that fails that check is dropped and the rest of the list is still honoured), and rides on the step’s payload so the agent renders the same policy. The agent is what renders that policy in your cluster, so until the agent release of 5 September 2026 reaches it, a step still gets the previous tier - 443 to every address but 169.254.169.254, and 53 to any pod.
• Image policy. A run or scan stage’s image is checked against ci_allowed_image_prefixes on the platform and again by the agent before anything runs; checkout and build always run Ankra’s own pinned images regardless of the organisation’s list. A named service’s image goes through the same check, and a sidecar outside the policy refuses the whole step rather than running beside it. The platform’s check is the one matched at a path boundary, and an entry ending in /, : or @ admits exactly that boundary rather than matching nothing (above). The agent’s own fallback check is still a plain textual prefix match, so a neighbouring registry path can satisfy it and a separator-terminated entry is read as plain text rather than as the boundary it names, until the agent release of 5 September 2026 reaches your cluster.
• Resources. A stage’s cpu and memory are the step’s limits. The step reserves half of the CPU (never under 100m, or the whole figure when the stage declares 100m or less) and all of the memory on its node, so it can use CPU up to its ceiling when the node has it free and can never take memory another step was given. 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, HOME, TMPDIR, XDG_RUNTIME_DIR and XDG_CACHE_HOME, or the image builder’s own BUILDKIT*, BUILDCTL, ROOTLESSKIT and DOCKER_CONFIG. A service the step names may not set them either - those variables decide what a container actually executes, and a sidecar’s process is no exception.
• Secrets and credentials. A declared binding is revealed once, to a file under /run/agent-secrets named after the binding, by the agent calling back with its own session token - never written into the step’s payload or a log line. A checkout step’s own git credential is granted the same way and read by a credential helper that answers only for the host it was minted for, so a malicious submodule URL cannot walk off with it.
• Forks. A pull request whose head lives in a fork - or whose provenance the delivery could not establish - runs with no secrets, no credentials and no identity beyond reading itself (fork_policy: read_only, the default). checkout and build both clone the fork’s own head anonymously - never the pipeline’s own repository - reading the head repository the trigger recorded on the run; checkout refuses outright, rather than guessing a remote, on the rare delivery whose fork head repository could not be established at all. build still runs (so a maintainer can see whether a contributor’s change compiles) but renders with no push target, so nothing it produces can reach a registry; scan may still pull the image it built to report on, never a private one. Every stage but checkout, build and scan runs with no network at all, regardless of what the fork’s own copy of the definition asks for - the tier is clamped, not merely left alone, so a fork-controlled network: egress-https on some other stage is not honoured just because these three need it. Beyond what such a run may touch, it is bounded in what it may spend: at most 8 matrix legs per stage, a 60-minute step timeout, 2 CPU and 4Gi per step, no sidecar services, no shared cache volumes, and 256 MiB of artifacts and logs for the whole run. The first four are imposed when the run is planned, so the plan a reviewer reads is the run that executes; caches are withheld at dispatch, and the artifact budget bounds what the run is granted from its declared sizes (the same ceiling on what actually arrived is in the artifact store, waiting on the settle lane that will call it). A plan_fork_budget: diagnostic names the ceilings, and one more diagnostic names each stage that hit one.
• 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 connecting a repository, 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, or a build step whose push target cannot be resolved: no application link, a component with no resolvable registry, or a stage that belongs to no component of the application), 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), build_runtime_confined (below), 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.
• build_runtime_confined: your nodes confine the image builder, and no setting relaxes it. A build stage runs rootless BuildKit in a pod that deliberately names no seccomp or AppArmor profile, because the Pod Security Baseline profile the ankra-ci-build namespace enforces forbids Unconfined - naming it would leave the pod refused by the very namespace admitting it. On a node whose runtime resolves “names none” to a confining profile - containerd on an Ubuntu host applying its default AppArmor profile, or a kubelet with seccomp defaulting applying RuntimeDefault - rootlesskit cannot make its mount namespace private, and the builder dies before BuildKit starts and before anything in your Dockerfile is read. The pod exits non-zero, so the agent reports it as your failure; it is not, and the settle loop re-classes it. There is no cluster, organisation or pipeline setting that renders the build pod Unconfined, and that is by design rather than an omission - nothing about a pod spec can defeat the node’s own default from inside Baseline. The supported answer is Ankra platform builders, which takes two things: ci_build_fallback: platform_builders, which is the default, and the platform builds grant, which Ankra makes per organisation on request (that section says how to confirm it and how to ask). With both, the retry, and every later build on that cluster, is routed to Ankra platform builders and the step’s executor records it. The verdict is remembered per cluster against the agent version and builder image it was observed under, so a cluster pays this failure once rather than on every run - and re-probes by itself when either moves. With the fallback set to none the build is refused instead, naming the containment and telling you to set the fallback or run the pipeline on a cluster whose runtime leaves the builder unconfined. With the fallback already platform_builders but the grant not yet made, the retry concludes build_fallback_none with a sentence saying Ankra’s platform-operated build fallback is not enabled for this organisation yet: no setting of yours changes that, so ask Ankra for the grant, then re-run. Every other stage kind is unaffected: checkout, test, scan and gate run in-cluster on a confining node exactly as anywhere else.
• Ankra’s, never retried. step_stranded - a step still pending after its run has outlived the sum of every step’s own timeout (capped at the same 6-hour ceiling one step is held to, plus a grace window). It concludes as infra_error with a sentence saying it never started and pointing at the cluster’s agent and its ci_worker_count. A fresh attempt is not written, because it would face the identical exhausted budget; the value of the sweep is that the run concludes rather than sitting open forever. report_unreadable joins it: a scan step that concluded successfully but whose report Ankra could not download or parse is revised to infra_error carrying “Ankra could not read the <report> report this step produced, so its findings were not recorded.” Ankra failing to read what a scanner said is not the same fact as the scanner having passed, so it is never recorded as clean. report_unreadable used to be what an organisation with no backup vault got on every scan step it ran; now that such an organisation’s artifacts go to the Ankra-managed default vault, it means what it says - the object was never uploaded, or came back unparseable. The remaining causes are a run that had already spent its 2 GiB artifact budget before the report was due, and a vault whose bucket stopped answering. With no ready vault on either side, a scan step is refused before it runs instead, with error class artifact_store_unavailable and the sentence “This step’s reports need a ready backup vault in the organisation, and there is none.” A step that had already failed, timed out or hit infra_error keeps its own verdict - that is a more specific answer than this one.
• 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. The run itself is heartbeated while any of this is going on, so a long pipeline is not failed by the platform’s own stale-run reaper for taking longer than twenty minutes.
• 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, whatever depends on them, and the steps they build on), 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. It re-plans from the original run’s own definition, not from whatever the pipeline has become since, so re-running a month-old run reproduces it rather than quietly executing a different pipeline.
• Failed-only re-runs start from an empty workspace. A re-run gets a workspace of its own - the original’s is removed once it concludes - so --failed-only re-runs the checkout and every upstream step whose output a repeated step reads (through needs, and for a gate the stages in its require_stages) together with the failed steps and their dependents. Steps that succeeded and that nothing repeated needs, such as a publish after the failure, are not repeated. A failed-only re-run that could not run a step that failed - a stage limited by when.events to push, which a re-run’s rerun trigger filters out - is refused with the reason for each such step, rather than queued to pass without it.

​

Diagnosis codes

​

Status is the lifecycle, outcome is the verdict

​

Limits and defaults

​

Bring your own CI (GitHub Actions)

​

Commands and API

​

What comes next

• The runner for verify (HTTP probes, smoke scripts, k6 load tests, PromQL assertions, restore verification).
• The per-run identity that permissions mints, so a step can call the ankra CLI with exactly the authority the default branch granted; cloud and object_storage credentials once it exists.
• The built-in ankra/* step library behind uses:, organisation step templates, and custom_tool/<name> steps.
• The executors for the preview (inside the pipeline DAG), agent, approval, webhook, automation, ankra and external stage kinds; on.webhook inbound dispatch tokens. Each of those stages validates with a warning and is skipped today, so declaring one costs you the stage, not the run.
• The user-declared retry block being applied; dynamic matrices that fan out over a previous step’s output; a dedicated run page in the portal (the Pipelines section shows runs today; a standalone page with more depth is still to come).
• Attestations and SBOM referrers carried onto the digest publish re-tags into your real repository, not only the one build pushes to staging.
• Merge-when-green, automatic disposition re-evaluation, and planning from the committed file at a run’s own commit, on GitLab and Bitbucket Cloud (GitHub only today).
• The agent release that publishes live step output on the dedicated pipeline_output stream the platform already reads. (The narrower egress-https with its ci_egress_allowed_cidrs allow-list, and the image-prefix boundary check, were listed here and have since shipped on both the platform and the agent - see What is in place today.)
• Environments hydrated from restore points, verification stages, promotions with approvals, and canary rollouts through Traefik weighted traffic.

​

Next steps