ankra pipeline
Manage Ankra Pipelines: in-cluster CI/CD runs, the pipeline definition of record, and its cron schedules. Every command addresses one pipeline with exactly one of:--repository takes the repository’s id
(for example, the “repository.id” field ‘ankra pipeline definition get’
returns). Most invocations want --application instead.
A run is addressed by its id (the RUN ID column, not the “run_id” field a
JSON/YAML response also carries - that second field is the cross-lifecycle
umbrella run this pipeline run belongs to, useful for correlating with
‘ankra cluster operations’, but not what these commands accept).
‘pipeline get’ can also select a run by its commit, branch or trigger, and
wait on or watch it - see ‘ankra pipeline get --help’.
‘pipeline definitions get|approve’ are the one exception: they address a
stored definition directly by its own id and take neither flag - see
‘ankra pipeline definitions --help’.
ankra pipeline artifacts
List a pipeline run’s stored step logs and declared artifacts, oldest first. Every step’s complete output is archived as a “step_log” artifact once the step concludes (‘ankra pipeline logs’ reads that one automatically for a concluded step); anything a stage’s own “artifacts:” block declared shows up as “artifact”. An empty first page means the run genuinely has nothing stored yet - no step has concluded, or the organisation has no ready backup vault to store into. STATUS is “pending” until the upload is confirmed, “uploaded” once “artifacts download” can fetch it, “failed” if it never arrived (see the row’s error), or “expired” once retention removed it. The listing is paged: it prints one server page (50 rows by default) and says when there is another, which--cursor reads. So a run with more
artifacts than one page shows its oldest first, and the list is complete
only once no further page is offered.
ankra pipeline artifacts download
Download a stored artifact, following the platform’s redirect to its presigned storage URL and streaming it to disk.ankra pipeline branches
List a pipeline’s branches, one row per ref, with the newest run on each. The repository’s default branch leads the listing; everything else follows by most recent activity. Each row carries the latest run on the ref, the outcome of the run concluded before it (PREVIOUS), how many runs the ref has ever had, and how many of those a newer commit superseded - a run cancelled because something newer took its concurrency group, which is history rather than a failure to look at. Branches with no run in the last fourteen days are hidden;--all shows them.
The count of what was hidden is printed after the table.
STATUS is the latest run’s lifecycle - queued, running or concluded - and
OUTCOME its verdict, which is empty until the run concludes. ‘ankra pipeline
get --help’ documents both fields.
ankra pipeline cancel
Cancel a pipeline run that has not concluded. A run that had started stops its main and on_failure stages, then runs its finally stages before it concludes cancelled. While they run the run reads “running” and “cancelling”. A run that never started concludes at once.--force skips the finally stages: the run concludes cancelled at once. On a
run that is already cancelling it stops the finally stages still running.
Cancelling such a run again without --force is refused.
ankra pipeline definition
Manage the pipeline definition of recordankra pipeline definition get
Show the pipeline definition of recordankra pipeline definition put
Store a generated pipeline definition server-side, replacing the repository’s definition of record. Requires the pipelines.manage permission. This does not touch the repository’s committed .ankra/pipeline.yaml: a committed file still wins for logic per the DescriptorOfRecord contract, so ‘put’ is for a repository whose pipeline Ankra generates and stores rather than one you author and commit yourself.ankra pipeline definitions
Read and grant an administrator’s approval of one stored pipeline definition’s protected sections: the authority-bearing parts of a pipeline - permissions, credentials, secrets scope, network tier, image policy, runs_on, environment gates and more - that a pull request may add logic around but never grant itself (“logic is open, authority is closed”). These two commands address one stored definition directly by its own id, unlike ‘pipeline definition get|put’ which read and write the definition of record for a repository or application. There is no lookup or listing route for a definition’s id. The one to approve is the repository’s current default-branch definition: ‘ankra pipeline get <run>’ prints its approve command on a run that is not approved (“approve_definition_id” in -o json), and a pull request’s status comment names it too. The run’s “authority_definition_id” is the definition its trusted authority came from: useful to inspect with ‘get’, but not the one to approve - it is normally already approved, and ‘approve’ refuses it. An approval applies to runs planned after it; a run keeps the authority it was planned under.ankra pipeline definitions approve
Record an administrator’s approval of one stored pipeline definition’s protected sections. Requires the pipelines.manage permission and a human actor - a service-account or agent token is refused. Approving grants whatever permissions, credentials, secrets scope, network tier and other protected sections the definition declares - inspect them first with ‘ankra pipeline definitions get <id>’ if you have not, since this command prints only the protected-sections hash, not their content. Confirms before approving;--yes skips the prompt for scripted use.
Only the repository’s CURRENT default-branch definition can be approved, and
only once: approving a definition the default branch has since moved past,
or one already approved, answers a 409 this command prints verbatim rather
than treating as success. A definition recorded before its protected
sections were ever hashed answers the same 409.
ankra pipeline definitions get
Show one pipeline definition’s protected-authority approval stateankra pipeline findings
List a pipeline run’s persisted scan findings. Findings are recorded once a “scan” step has concluded for the run’s own commit; a run with no scan step, or one still running, answers an empty list rather than an error. The default table sorts worst severity first and groups by tool, so the findings most likely to block a “gate” step are always at the top; -o json/yaml prints every field the server carries, including each finding’s tool-specific detail.ankra pipeline get
Show a pipeline run’s detail - or wait for it to conclude, or watch it. Name the run by its id, or select it by what you know about it. Push and pull request runs are started by the webhook, so a CI job or an agent usually knows the commit rather than the run id:--head-sha, --branch and --trigger narrow
the pipeline’s runs the way ‘pipeline list’ filters them. Exactly one match is
that run; when several match, --latest takes the newest, and without it the
command lists them instead of guessing. --latest on its own is the pipeline’s
newest run.
--wait blocks until the run concludes, then prints its final detail. --watch
prints every state change of the run and of each of its steps as it is seen,
until the run concludes; with -o json each change is one JSON object on its
own line, carrying the run or step as the platform answered it. --timeout
bounds either one; without it they wait as long as the run takes. When a
selection matches no run yet, --wait and --watch wait for one to appear - the
webhook that creates it can land a moment after you ask - for up to
--timeout, or ten minutes when no --timeout is set.
Exit codes: 0 when the run succeeded; 1 when it concluded any other way, or
the platform could not be read; 2 when a selection matches several runs and
--latest was not given; 3 when nothing matches; 5 when --timeout ran out or,
with --exit-code, when the run has not concluded yet. Without --wait, --watch
or --exit-code the command exits 0 whatever the run’s outcome, as it always
has.
Status and outcome (-o json): ‘status’ is the lifecycle, never the verdict.
A run’s status is queued, running or concluded; a step’s is blocked (waiting
on its dependencies), pending (ready, not yet claimed), running or concluded.
How the work ended is the separate ‘outcome’ field, which is null until the
status is concluded and then always one of: success, failure (the work
itself failed), cancelled, timed_out, skipped (it never ran - a dependency
did not succeed, a condition or the trigger filter excluded it) or
infra_error (Ankra failed, not the work). The same two fields with the same
vocabulary sit on the run and on each step, mirroring GitHub Actions’
status/conclusion split - so a monitor that filters on status finds every
finished run under concluded, and must read outcome for whether it passed.
The human-readable Status line and STATUS column print the outcome once
there is one and the status until then, with a glyph that says which:
✓ success, ✗ failure / timed_out / infra_error, ⊘ cancelled, ○ skipped, and
⟳ only for a run or step that has not concluded (○ for a blocked step).
Superseded runs: a run cancelled because a NEWER run took its concurrency
group reads ‘superseded’ rather than ‘cancelled’ - on the Status line, in
the STATUS column, on the last line of --watch and in the conclusion --wait
reports - and ‘pipeline get’ names the run that took its place. Nobody
stopped that run, and the run worth looking at is the newer one. Only the
word differs: --wait, --watch and --exit-code exit 1 for a superseded run as
for any cancelled one. In -o json the fields are ‘error_class’
(“superseded”), ‘superseded_by_run_id’ and ‘superseded_by_run_number’;
‘outcome’ stays “cancelled”, so a script filtering on outcome alone still
finds these runs and must read the class to tell them from a run somebody
cancelled.
Cancelled runs (-o json ‘cancelled_by’, ‘cancel_reason’, ‘cancelled_at’;
the Cancelled line): who stopped a run, why and when. ‘cancelled_by’ is the actor
in the same form ‘requested_by’ uses - “user:<id>” for a cancel pressed in
the portal, the CLI or the API, “github:<login>” for the Cancel action on a
pull request’s check run, “concurrency:<run id>” for a supersession,
“merge_train:<entry id>” for the merge train - and ‘cancel_reason’ is one of:
ankra pipeline list
List a pipeline’s runs, newest first.--status filters on the run’s lifecycle - queued, running or concluded - not
on how it ended: every finished run is concluded, and its verdict is the
separate ‘outcome’ field (success, failure, cancelled, timed_out, skipped or
infra_error), which the STATUS column prints in place of the status once
there is one - except for a run a newer run superseded, which reads
‘superseded’ rather than ‘cancelled’. ‘ankra pipeline get --help’ documents
both fields, supersession and the run’s ‘authority_state’.
--latest-per-branch answers the other question a listing is usually opened
for: not the last N runs of everything, but the newest run of each branch.
It prints the same table as ‘ankra pipeline branches’ - see that command’s
help - and cannot be combined with the run filters, which narrow runs rather
than refs.
ankra pipeline logs
Show a pipeline step’s output. A step that has already concluded prints its complete log in one shot ---follow does nothing extra for it, since there is nothing left to produce.
Its archived log is read when the run has one; archiving needs a ready backup
vault, and when there is none the command replays the step’s output from the
platform’s retained log stream instead and stops when that runs out. A log
still being archived - asked for the moment its step ended - is waited for,
for up to a minute, before the command falls back to that replay; it exits 5
only when neither copy can be read.
A step that is still running is followed over the live log stream: without
--follow, the command tails the step until it concludes and then stops; with
--follow it keeps reconnecting through a dropped stream instead of giving up.
A live connection starts from the moment it connects unless you pass
--replay, which asks the platform for the output the step already produced
first.
A step that has not started yet has no log stream. With --follow the command
waits for it - saying what it is blocked on - and attaches as soon as the
step starts; a step that concludes without ever starting prints its outcome
and whatever log it does have. One invocation spends at most 30 minutes
waiting, in total across every time the step goes back to waiting. Without
--follow the command says the step has not started and stops.
A step Ankra runs on its own lanes never gets a live stream at all: a build
the platform builders took over because the run’s cluster cannot build it,
and a gate, publish or approval the platform settles itself. Its log is
archived and printed here once the step concludes. ‘ankra pipeline get’ marks
those steps in the EXECUTOR column; with --follow the command waits for such
a step to conclude and then prints the archived log, and without it the
command says where the step is running and stops.
A step Ankra retried is several attempts under one key, each with its own
log. --step <key> shows the newest attempt - the one that did the work - and
names the earlier ones on stderr; pass --step <attempt id>, as
‘ankra pipeline get’ prints it, to read one of those instead.
ankra pipeline repositories
Connect a bare Git repository to Ankra Pipelines, list what the organisation has connected, read one by id, and disconnect one. A connected repository is what a push, pull request or tag webhook resolves against to start a run. Connecting one here does not require an Ankra application - use it for a repository with no application (docs, website, values repos) or before one exists; an application already on Ankra links to its own repository automatically.ankra pipeline repositories connect
Connect a bare Git repository to Ankra Pipelines: a push, pull request or tag webhook on it can then start a run. Connecting a repository that is already connected does not create a second row or refresh the first - the platform refuses with the existing repository’s id named in the error, so a setup script that runs this unconditionally can still learn the id it has either way.--application links the repository to an application already in this
organisation (by id) without changing that application’s own pipeline
source - it is refused (422) for an application outside the organisation.
--cluster overrides the organisation’s declared CI cluster
(‘ankra ci-settings’ / GET /org/ci-settings) for just this repository’s
pipelines - it is refused (422) for a cluster outside the organisation, or
one whose agent has not advertised it can run pipeline steps.
For a GitHub repository, the committed .ankra/pipeline.yaml on the default
branch (read through --credential) is recorded as the definition of record in
the same call when it parses. A repository with no committed file, or on
another provider, connects with no definition - store one with
‘ankra pipeline definition put --repository <id> <file>’. Running connect a
second time will not pick up a file committed since, because an already-
connected repository is refused rather than re-read (see above); disconnect
the repository and connect it again to force a fresh read.
--workspaces-only connects the repository for Ankra Workspaces alone
(‘ankra exec’, ‘ankra workspace’): its committed pipeline file is not read,
no definition is recorded, no push, pull request, tag, schedule or manual
dispatch starts a run, and no commit status or check run is posted. Use it
for a repository whose pipeline already runs somewhere else. Switch an
already-connected repository with ‘ankra pipeline repositories set-mode’.
ankra pipeline repositories disconnect
Disconnect a connected repository: from then on a push, pull request or tag webhook against it starts no run, and it drops out of ‘ankra pipeline repositories list’/‘get’. This is reversible by construction - connecting the same provider/owner/name again revives this exact row, definitions, runs, artifacts and findings kept - so disconnecting is not a delete. A repository with a pipeline run still queued or running refuses to disconnect (409); cancel or wait for it to conclude, then disconnect again.ankra pipeline repositories get
Show one connected repository by id. There is no lookup by owner/name yet, only by id - run ‘ankra pipeline repositories list’ to find it.ankra pipeline repositories list
List the organisation’s connected pipeline repositoriesankra pipeline repositories set-cluster
Change a connected repository’s CI cluster override without disconnecting it.--cluster clears the override, so the repository’s
runs follow the organisation’s CI settings - its pipeline cluster, or its CI
pool - again.
It changes where the repository’s next runs go; a run already queued or
running keeps the cluster it was pinned to, because a run’s steps never split
across clusters. Requires the pipelines.manage permission.
ankra pipeline repositories set-mode
Switch a connected repository’s mode without disconnecting it.ankra pipeline rerun
Open a new run from a run that already happened. The new run is a fresh run, not a retry of the old one: the old run’s outcome stays the record of what happened. The new run is recorded with trigger ‘rerun’, and ‘rerun_of_run_id’ ties the two together. A re-run repeats the original event. A re-run of a push run is planned as a push, so its push-only stages run. A re-run of a pull request run (or of a merge train car) is planned as a pull request, and a re-run of a schedule run as that schedule. A re-run of a tag run or of a manual or API dispatch is planned as a plain re-run, so stages limited to other events are skipped. A re-run’s publish pushes the sha- image, but that image does not become the push-to-deploy candidate, so a re-run does not roll the deployment.--failed-only restricts the new run to the steps that failed, the steps that
were skipped because of a failure, whatever depends on them, and the steps
they build on. The new run starts from an empty workspace, so the checkout and
every upstream step whose output a repeated step reads run again with it;
steps that succeeded and that nothing repeated needs do not. A failed-only
re-run that would still skip one of those steps (for example a tag-only
release behind a failed build, on a re-run of a tag run) is refused with the
reason rather than passing without it.
--full sets the pipeline’s path filters aside for the new run, so every stage
whose filters left it out runs, and the run records that you asked. A re-run
of a run that was already a full run is one again without the flag.
ankra pipeline run
Dispatch a manual run of a pipeline’s stored definition. A run executes one commit, and Ankra checks it against the repository’s own host before anything is queued: a--sha that is not reachable from --ref (or
the repository’s default branch) on that repository is refused.
Without --sha, the commit is:
- the working directory’s HEAD, when the checkout is the repository the
pipeline builds and
--refis not given.--applicationis read from the checkout too, so ‘ankra pipeline run’ on its own runs what you are looking at; - otherwise the tip of
--ref, or of the default branch, which Ankra reads from the repository’s host when it dispatches.
--application other-app’ from the wrong directory runs
other-app’s default branch, not your local HEAD.
--full runs every stage: the pipeline’s path filters (on.<event>.paths,
when.paths and paths:) are set aside for this run, and the run records that
you asked. A stage’s if: still decides.
ankra pipeline schedules
Manage a pipeline’s cron schedulesankra pipeline schedules create
Add a cron scheduleankra pipeline schedules delete
Remove a cron scheduleankra pipeline schedules list
List a pipeline’s cron schedulesankra pipeline schedules update
Change a cron schedule. Every flag is optional and only what is given changes - an update that names only--enabled leaves the cron, timezone, ref,
and inputs exactly as they were.
ankra pipeline tests
Show the test results Ankra recorded for a pipeline run. A stage declares the reports its test command writes under test_results (JUnit, go test -json, pytest or Playwright), and Ankra reads every test’s outcome from them. ‘ankra pipeline tests <run>’ lists the run’s reports and what became of each, then its failed, flaky and slowest tests. A run that declared no reports says so: that is not a passing run.--help’): a run step whose only failed tests are quarantined then
succeeds. The run’s summary still lists those tests under Failed, and lists
them again in a “Quarantined failures” section that says whether each one’s
step was forgiven or failed anyway because another test failed too.
ankra pipeline tests history
Show one test’s outcomes in the newest runs of a branch (the repository’s default branch unless--branch names another) and its flaky and failure rates
over them. Only the branch’s own runs count (push, schedule, manual): a pull
request ran code the branch does not have.
ankra pipeline tests quarantine
The flaky test quarantine lets a repository keep a known-flaky test from failing its pipeline runs while someone fixes it. It is off until you turn it on (‘ankra pipeline tests quarantine settings--enable’, pipelines.manage). A test may be quarantined when, over the default
branch’s own runs (never a pull request check) in the last 30 days, it ran in
at least --min-samples runs (default 20) and was flaky - failed, then passed
on a retry - in at least --min-flaky-rate of them (default 0.1, 10%).
‘candidates’ lists exactly the tests that qualify; ‘add’ quarantines one.
A quarantined test still runs and is still reported. What changes: a failing
‘run’ step whose ONLY failed tests are quarantined, read from test reports
the step uploaded whole, succeeds instead, and the steps after it run. A step
that also failed another test, failed on a timeout or infrastructure error,
or whose reports could not be read fails exactly as before.
A quarantine releases itself after --release-after passes in a row on the
default branch (default 10); a failed or flaky run starts the count again.
‘release’ ends one by hand.
Nothing is hidden: ‘ankra pipeline tests <run>’ still lists every failed
test, and lists the quarantined failures in a section of their own whether or
not they rescued their step. ‘ankra pipeline get <run>’ says which steps the
quarantine forgave.
With no subcommand, shows the settings, the quarantined tests and the ones
released in the last 30 days (the same as ‘quarantine list’).
ankra pipeline tests quarantine add
Quarantine one test, by the key ‘quarantine candidates’, ‘tests <run> -o json’ and ‘tests history’ print for it.--reason is required (1 to 500 characters)
and is shown beside the quarantine.
The platform refuses while the quarantine is off for the repository, for a
test that is not flaky enough on the default branch (it says the test’s rate
and the thresholds), for a test already quarantined, and for a test with no
default-branch result in the last 30 days. Needs pipelines.manage.
ankra pipeline tests quarantine candidates
List the tests that qualify for quarantine, most flaky first: tests that, over the default branch’s own runs in the last 30 days, ran in at least the repository’s minimum number of runs and were flaky in at least its minimum share of them, and are not quarantined already. Quarantine one with ‘ankra pipeline tests quarantine add <test key>--reason "..."’.
ankra pipeline tests quarantine list
Show the repository’s quarantine settings, every quarantined test (how flaky it was when quarantined, its default-branch passes in a row towards its release, and who quarantined it), and the tests released in the last 30 days with why. -o json/yaml prints every field the server carries.ankra pipeline tests quarantine release
Release a quarantined test: from the next run on, a step that fails it fails. Name the quarantine by its id (‘quarantine list’ prints it) or by the test’s key, which is looked up among the repository’s live quarantines.--reason is
optional (at most 500 characters). A quarantine also releases itself after
enough default-branch passes in a row. Needs pipelines.manage.
ankra pipeline tests quarantine settings
Turn the repository’s test quarantine on or off and set when a test may be quarantined and when one releases itself. Only the flags you pass are sent; the others keep their stored values. With no flag, prints the settings.ankra pipeline tests timings
Show each file’s (or, with--group-by test, each test’s) mean recorded
duration for one stage across the newest runs of a branch, slowest first: the
input a sharding script balances its shards by. When nothing has been
recorded for the stage on the branch yet the command says so; fall back to an
even split rather than reading that as every test taking no time.
ankra pipeline time-saved
Show how much CI time path filters and promoted publishes saved over the last 7 or 30 days: for one pipeline with--application or --repository, or
for the whole organisation with neither.
Each figure is an estimate the platform made when a run was planned or
skipped, from the stage’s own recent history in the repository: the median of
its newest 20 successful runs. A stage with no history is counted as unknown
and is never added to a total. The time is runner time (step-seconds), not
wall-clock time. Only runs planned after the platform started recording this
are counted.
‘ankra pipeline get <run>’ shows what one run saved.
ankra pipeline train
Manage a repository’s Ankra merge train. The merge train tests each pull request squashed onto the base branch and the pull requests ahead of it, exactly as its merge will land, and merges it through the repository host’s own merge when that run passes. Every merge is then a tree a pipeline run already passed, so a definition whose publish stage declares promote_from: pull_request publishes the tested image instead of rebuilding it. The train is off by default: ‘ankra pipeline train enable’ switches it on (pipelines.manage). ‘ankra pipeline train add <pull request>’ puts a pull request at the end of it, ‘list’ shows it in order and ‘remove’ takes one out. GitHub repositories only. The train merges under the Ankra GitHub App’s identity, so adding or removing a pull request needs pipelines.operate and, on top of it, one of: you are an organisation administrator, you opened the pull request, or you have write access to the repository on GitHub. Ankra reads the last two through the GitHub identity you linked with OAuth from the Ankra portal. One exception: with pipelines.operate you can always remove an entry you added yourself, with or without a linked identity. Otherwise, without a linked identity only an administrator can add or remove. If GitHub cannot be asked, the request is refused and nothing changes.ankra pipeline train add
Put a pull request at the end of the merge train. The train tests the pull request’s head as it is now: pass--head-sha to pin
the commit you reviewed. A push to the pull request after it entered takes it
out of the train again. A pull request already in the train is answered with
its entry.
You must be an organisation administrator, the pull request’s author, or have
write access to the repository on GitHub (through the GitHub identity you
linked from the Ankra portal), as well as pipelines.operate.
ankra pipeline train disable
Switch the merge train off and empty itankra pipeline train enable
Switch the merge train onankra pipeline train list
Show the merge train in order, and what recently left itankra pipeline train remove
Take a pull request out of the merge train. You can always remove an entry you added yourself. Removing anyone else’s needs the authority adding it would: organisation administrator, the pull request’s author, or write access to the repository on GitHub, as well as pipelines.operate.ankra pipeline validate
Dry-run a pipeline definition: parse it, validate it, and plan it for a synthetic push and a synthetic pull request, without writing anything. Defaults to .ankra/pipeline.yaml when no file is given; with neither that file nor a--application/--repository definition already stored, there is nothing to
validate. Passing a file validates its content directly, which is what a
‘is my pipeline.yaml correct before I commit it’ check wants. --spec-file is
the flag spelling of that argument, matching ‘pipeline run --spec-file’.
After the per-event detail, a table shows every stage against every event
probed (push, pull_request, and tag when the pipeline declares on.tag):
“run”, or “skip” with the planner’s reason. Path filters - flat when.paths or
an event block’s when.pull_request.paths / when.push.paths - cannot decide
without a diff, so they pass with a diagnostic; --changed-file (repeatable)
names a dry-run diff so they decide for real:
--changed-file, inside a git checkout, the CLI runs
the same analysis against the working tree and shows which of those stages
the change reaches (“graph: affected”) and which it does not (“graph: not
affected”, skipped and satisfied for the stages that need it).
--no-local-graph skips that and shows them as decided at run time.
--ref reads the definition from a git reference in the current checkout
instead of the working tree, so a candidate on a branch can be checked
before it is merged: