> ## Documentation Index > Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt > Use this file to discover all available pages before exploring further. # ankra pipeline > Manage Ankra Pipelines ## 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: ```text theme={null} --application the application the pipeline builds and deploys --repository the pipeline repository directly ``` There is no lookup route yet for a repository by "owner/name" - only by-id and by-application addressing exist - so `--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. ```bash theme={null} ankra pipeline artifacts [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--cursor` | | Page cursor from a previous listing's next\_cursor | | `--limit` | `0` | Maximum number of artifacts to return (server default 50, max 100) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra pipeline artifacts download Download a stored artifact, following the platform's redirect to its presigned storage URL and streaming it to disk. ```bash theme={null} ankra pipeline artifacts download [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--out` | | Local file to write the artifact to (default: the artifact id, in the current directory) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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. ```bash theme={null} ankra pipeline branches [flags] ``` **Examples** ```bash theme={null} # Where does every branch of the application you are standing in stand ankra pipeline branches # Include the branches nothing has run on for a fortnight ankra pipeline branches --application orders-api --all # The branch whose latest run did not succeed, for a script ankra pipeline branches --application orders-api -o json | jq '.branches[] | select(.latest_run.outcome != "success")' ``` **Flags** | Flag | Default | Description | | - | - | - | | `--all` | `false` | Include branches with no run in the last 14 days, which are hidden by default | | `--application` | | Application name or id whose pipeline to act on | | `--cursor` | | Page cursor from a previous listing's next\_cursor | | `--limit` | `0` | Maximum number of branches to return (server default 20, max 100) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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. ```bash theme={null} ankra pipeline cancel [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--force` | `false` | Skip the run's finally stages, or stop them if the run is already cancelling | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra pipeline definition Manage the pipeline definition of record ## ankra pipeline definition get Show the pipeline definition of record ```bash theme={null} ankra pipeline definition get [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra 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. ```bash theme={null} ankra pipeline definition put [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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 \' 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 \' 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. ```bash theme={null} ankra pipeline definitions approve [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--yes` | `false` | Skip the confirmation prompt | ## ankra pipeline definitions get Show one pipeline definition's protected-authority approval state ```bash theme={null} ankra pipeline definitions get [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | ## ankra 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. ```bash theme={null} ankra pipeline findings [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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:\" for a cancel pressed in the portal, the CLI or the API, "github:\" for the Cancel action on a pull request's check run, "concurrency:\" for a supersession, "merge\_train:\" for the merge train - and 'cancel\_reason' is one of: ```text theme={null} user_requested somebody cancelled it in the portal, the CLI or the API source_control the Cancel action on its check run superseded a newer run took its concurrency group queued_replaced a newer commit replaced it before it started merge_train the merge train no longer needed this change tested pull_request_closed its pull request merged or closed (no actor) step_cancelled nobody cancelled it: a step was stopped where it ran, for example when the cluster's agent shut down, and the Error line carries that step's sentence (no actor) ``` superseded, queued\_replaced and merge\_train runs read 'superseded' (above). A reason this list does not name yet is printed as it is. All three fields are null for a run nobody cancelled and for one cancelled before Ankra recorded this, which is "not recorded", never "the platform did it". Steps that never started (error\_class "never\_scheduled"): a step whose time ran out while no node had room for what it requests concludes timed\_out, and so does its run, but nothing ran. The Class line says so; free capacity on the cluster, add a node, or lower the stage's resources, then rerun. Authority (-o json 'authority\_state', the Authority line): the protected authority the run executed under. 'approved' - the default branch's definition declares no protected section, or an administrator approved exactly what it declares, and the head changes nothing. 'unapproved' - a run of the default branch whose definition changed authority no administrator has approved yet; it executes under the last approved authority, or under none when nothing was ever approved. 'changed\_on\_head' - a run of another branch or a pull request whose definition declares different authority; it executes under the default branch's, and the head's change is ignored and reported. null - the planner never resolved authority for this run: it is still queued, it concluded skipped because its trigger filter excluded every stage before planning, or it was planned before authority was recorded. null is "not recorded", never "no authority". ```bash theme={null} ankra pipeline get [run] [flags] ``` **Examples** ```bash theme={null} # Block until the pull request run for a commit concludes; exit non-zero unless it passed ankra pipeline get --head-sha "$(git rev-parse HEAD)" --trigger pull_request --latest --wait --timeout 45m # React to each run and step state change as it happens, one JSON object per line ankra pipeline get --watch -o json # Read a run once and branch on it: 0 passed, 1 did not, 5 still running ankra pipeline get --exit-code ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--branch` | | Select the run for this trigger branch instead of naming its id | | `--exit-code` | `false` | Exit 1 when the run concluded without succeeding, and 5 while it has not concluded (`--wait` and `--watch` always exit this way) | | `--head-sha` | | Select the run for this full commit sha instead of naming its id | | `--latest` | `false` | Take the newest matching run when several match (on its own: the pipeline's newest run) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--step` | | Also print the per-cache table of the step with this key: each cache's outcome, reason, size and save | | `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) | | `--trigger` | | Select the run with this trigger: push, pull\_request, tag, schedule, manual, api, agent, or rerun | | `--wait` | `false` | Wait for the run to conclude, then print its final detail; exits non-zero unless it succeeded | | `--watch` | `false` | Print each run and step state change as it happens until the run concludes (-o json: one JSON object per line) | ## 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. ```bash theme={null} ankra pipeline list [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--all` | `false` | With `--latest-per-branch`, include branches with no run in the last 14 days | | `--application` | | Application name or id whose pipeline to act on | | `--branch` | | Filter by trigger branch | | `--cursor` | | Page cursor from a previous listing's next\_cursor | | `--head-sha` | | Filter by the exact full commit sha | | `--latest-per-branch` | `false` | List one row per branch with the newest run on each, the table 'ankra pipeline branches' prints | | `--limit` | `0` | Maximum number of runs to return (server default 50, max 100); with `--latest-per-branch`, the number of branches (server default 20) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--status` | | Filter by run status: queued, running, or concluded | | `--trigger` | | Filter by trigger: push, pull\_request, tag, schedule, manual, api, agent, or rerun | ## 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` \ shows the newest attempt - the one that did the work - and names the earlier ones on stderr; pass `--step` \, as 'ankra pipeline get' prints it, to read one of those instead. ```bash theme={null} ankra pipeline logs [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--follow` | `false` | Wait for the step to start if it has not, then keep streaming, reconnecting through transient stream faults, until it concludes; for a step on Ankra's platform builders, which has no live stream, wait for it to conclude and print its archived log | | `--replay` | `false` | Also show the output a running step produced before this command connected (a concluded step's log is always shown whole) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--step` | | Step key to follow (required when the run has more than one step), or the id of one attempt of it as 'ankra pipeline get' prints for a retried step | ## 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` \ \'. 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'. ```bash theme={null} ankra pipeline repositories connect [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application id to link this repository to (optional; must belong to this organisation) | | `--cluster` | | Cluster id to run this repository's pipelines on, overriding the organisation default (optional; its agent must support pipeline steps) | | `--credential` | | Organisation Git credential used to read the repository; omit to connect without reading the committed pipeline file | | `--default-branch` | | Branch the pipeline file is read from (default: main) | | `--name` | | Repository name | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--owner` | | Repository owner or organisation | | `--provider` | | Repository provider: github, gitlab, or bitbucket | | `--workspaces-only` | `false` | Connect for Ankra Workspaces only: no pipeline runs, commit statuses or check runs, and the pipeline file is not read | ## 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. ```bash theme={null} ankra pipeline repositories disconnect [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--yes` | `false` | Skip the confirmation prompt | ## 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. ```bash theme={null} ankra pipeline repositories get [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | ## ankra pipeline repositories list List the organisation's connected pipeline repositories ```bash theme={null} ankra pipeline repositories list [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--cursor` | | Page cursor from a previous listing's next\_cursor | | `--limit` | `0` | Maximum number of repositories to return (server default 50, max 100) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--provider` | | Repository provider: github, gitlab, or bitbucket (filter) | ## ankra pipeline repositories set-cluster Change a connected repository's CI cluster override without disconnecting it. ```bash theme={null} ankra pipeline repositories set-cluster --cluster build-cluster ankra pipeline repositories set-cluster --cluster "" ``` The cluster (name or id) must belong to the organisation and its agent must run pipeline steps. An empty `--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. ```bash theme={null} ankra pipeline repositories set-cluster [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--cluster` | | Cluster name or id the repository's runs go to; empty clears the override | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | ## ankra pipeline repositories set-mode Switch a connected repository's mode without disconnecting it. ```bash theme={null} ankra pipeline repositories set-mode workspaces-only ankra pipeline repositories set-mode pipelines ``` workspaces-only keeps Ankra Workspaces ('ankra exec', 'ankra workspace') working and stops everything else: no push, pull request, tag, schedule or manual dispatch starts a run, no commit status or check run is posted, and the committed pipeline file is not read. It is refused (409) while a pipeline run is queued or running; cancel it or wait for it to conclude first. pipelines makes it an ordinary pipeline repository again: its committed .ankra/pipeline.yaml is read on the next reconcile and its webhooks start runs. Requires the pipelines.manage permission. ```bash theme={null} ankra pipeline repositories set-mode [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | ## 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. ```bash theme={null} ankra pipeline rerun [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--failed-only` | `false` | Re-run only the steps that did not succeed, whatever depends on them, and the steps they build on (checkout included) | | `--full` | `false` | Run every stage: set the pipeline's path filters aside for the new run | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) | | `--wait` | `false` | Wait for the new run to conclude before returning | ## 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 `--ref` is not given. `--application` is 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. A checkout of any other repository never supplies the commit, so 'ankra pipeline run `--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.\.paths, when.paths and paths:) are set aside for this run, and the run records that you asked. A stage's if: still decides. ```bash theme={null} ankra pipeline run [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--full` | `false` | Run every stage: set the pipeline's path filters aside for this run | | `--input` | `[]` | Dispatch input as key=value (repeatable) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--reason` | | Human note recorded on the run | | `--ref` | | Git reference to run at (defaults to the repository's default branch) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--sha` | | Full commit sha to run (defaults to HEAD of a checkout of this pipeline's repository, else the tip of `--ref`) | | `--spec-file` | | Run this pipeline definition instead of the stored one (requires pipelines.manage) | | `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) | | `--wait` | `false` | Wait for the run to conclude before returning | ## ankra pipeline schedules Manage a pipeline's cron schedules ## ankra pipeline schedules create Add a cron schedule ```bash theme={null} ankra pipeline schedules create [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--cron` | | Cron expression (required) | | `--enabled` | `true` | Whether the schedule fires | | `--input` | `[]` | Dispatch input as key=value (repeatable) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--ref` | | Git reference the schedule runs at (default the repository's default branch) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--timezone` | | IANA timezone the cron is evaluated in (default UTC) | ## ankra pipeline schedules delete Remove a cron schedule ```bash theme={null} ankra pipeline schedules delete [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--yes` | `false` | Skip the confirmation prompt | ## ankra pipeline schedules list List a pipeline's cron schedules ```bash theme={null} ankra pipeline schedules list [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra 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. ```bash theme={null} ankra pipeline schedules update [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--cron` | | New cron expression | | `--disabled` | `false` | Disable the schedule | | `--enabled` | `false` | Enable the schedule | | `--input` | `[]` | Replace the dispatch inputs entirely, as key=value (repeatable) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--ref` | | New git reference | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--timezone` | | New IANA timezone | ## 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 \' 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. ```bash theme={null} ankra pipeline tests one run's summary ankra pipeline tests history one test across the branch's runs ankra pipeline tests timings --stage mean durations, for sharding ankra pipeline tests quarantine the repository's flaky test quarantine ``` The test key is the one 'tests \ -o json' prints for each test. -o json/yaml prints every field the server carries. A repository can quarantine a known-flaky test ('ankra pipeline tests quarantine `--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. ```bash theme={null} ankra pipeline tests [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--slowest` | `10` | How many of the slowest tests to list (0 to 50) | ## 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. ```bash theme={null} ankra pipeline tests history [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--branch` | | Branch to read (default: the repository's default branch) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--runs` | `0` | How many of the newest runs to look back over (1 to 100; default 30) | ## 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 \' 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 \' 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'). ```bash theme={null} ankra pipeline tests quarantine [flags] ``` **Examples** ```bash theme={null} ankra pipeline tests quarantine ankra pipeline tests quarantine candidates ankra pipeline tests quarantine add --reason "times out on the shared runner" ankra pipeline tests quarantine release --reason "fixed in #123" ankra pipeline tests quarantine settings --enable --min-flaky-rate 0.2 ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra pipeline tests quarantine add Quarantine one test, by the key 'quarantine candidates', 'tests \ -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. ```bash theme={null} ankra pipeline tests quarantine add [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--reason` | | Why the test is quarantined (required, 1 to 500 characters) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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 \ `--reason "..."`'. ```bash theme={null} ankra pipeline tests quarantine candidates [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--limit` | `0` | How many candidates to list (1 to 100; default 50) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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. ```bash theme={null} ankra pipeline tests quarantine list [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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. ```bash theme={null} ankra pipeline tests quarantine release [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--reason` | | Why the quarantine is released (optional, at most 500 characters) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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. ```text theme={null} --enable / --disable whether a step whose only failed tests are quarantined succeeds (off by default) --min-flaky-rate 0.1 the share of default-branch runs a test must have been flaky in (greater than 0, at most 1) --min-samples 20 over at least this many observed runs (3 to 1000) --release-after 10 release after this many passes in a row (1 to 100) ``` Turning it off keeps the quarantined tests: their failures fail their steps again until it is turned back on. Needs pipelines.manage to change. ```bash theme={null} ankra pipeline tests quarantine settings [flags] ``` **Examples** ```bash theme={null} ankra pipeline tests quarantine settings ankra pipeline tests quarantine settings --enable ankra pipeline tests quarantine settings --min-flaky-rate 0.2 --min-samples 30 --release-after 15 ankra pipeline tests quarantine settings --disable ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--disable` | `false` | Turn the quarantine off (the quarantined tests are kept) | | `--enable` | `false` | Turn the quarantine on | | `--min-flaky-rate` | `0` | Share of default-branch runs a test must have been flaky in to be quarantined (greater than 0, at most 1) | | `--min-samples` | `0` | Observed default-branch runs that rate must rest on (3 to 1000) | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--release-after` | `0` | Default-branch passes in a row that release a quarantine (1 to 100) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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. ```bash theme={null} ankra pipeline tests timings --stage [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--branch` | | Branch to read (default: the repository's default branch) | | `--group-by` | `file` | Group by "file" or "test" | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--runs` | `0` | How many of the newest runs to sample (1 to 100; default 30) | | `--stage` | | Stage whose tests to time (required) | ## 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 \' shows what one run saved. ```bash theme={null} ankra pipeline time-saved [flags] ``` **Examples** ```bash theme={null} # The organisation over the last 30 days ankra pipeline time-saved # One application's pipeline over the last 7 days, as JSON ankra pipeline time-saved --application my-app --window 7d -o json ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--window` | `30d` | How far back to count: 7d or 30d | ## 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 \' 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. ```bash theme={null} ankra pipeline train add [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--head-sha` | | Full commit sha to pin as the head the train tests and merges | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra pipeline train disable Switch the merge train off and empty it ```bash theme={null} ankra pipeline train disable [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra pipeline train enable Switch the merge train on ```bash theme={null} ankra pipeline train enable [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--max-cars` | `1` | How many pull requests are tested at once (1-8), each stacked on the ones ahead of it | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra pipeline train list Show the merge train in order, and what recently left it ```bash theme={null} ankra pipeline train list [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## ankra 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. ```bash theme={null} ankra pipeline train remove [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | ## 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: ```bash theme={null} ankra pipeline validate --repository --changed-file frontend/app.ts ``` A stage that declares affected: (Go packages or pnpm workspace packages) is decided at run time by the run's checkout, from the dependency graph of the commit it checks out. With `--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: ```bash theme={null} ankra pipeline validate --ref origin/my-branch --application my-app ``` The reference is resolved locally, so a branch someone else pushed needs a 'git fetch' first, and the path is read from the repository root. ```bash theme={null} ankra pipeline validate [file] [flags] ``` **Flags** | Flag | Default | Description | | - | - | - | | `--application` | | Application name or id whose pipeline to act on | | `--changed-file` | `[]` | Plan as if this repository-relative path changed (repeatable), so path filters decide instead of passing | | `--no-local-graph` | `false` | Do not read the dependency graph of the local checkout for affected: stages | | `-o`, `--output` | | Output format: json or yaml (default: human-readable) | | `--ref` | | Read the definition from this git reference in the current checkout (for example origin/my-branch) instead of the working tree | | `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) | | `--spec-file` | | Validate this definition file, the same as passing it as the argument | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.