A
kind: deploy stage does not deploy to Kubernetes: it releases a bundle to host targets outside a cluster. Use one of the two routes above for a cluster.
Before you start
- A pipeline that runs. The repository is connected, a CI cluster has workers, and pull request runs go green. If not, follow Set up and run Ankra Pipelines first.
- A
gatebefore everypublish. Apublishstep refuses by name when its run has no successfulgateupstream that judged the same digest the build pushed. - Someone who can approve.
promote_fromandsecretsare protected sections, so a member withpipelines.manage, signed in as a person, approves the definition on the default branch (Approve the definition’s protected authority). - For the application route: the application has been deployed once, by
ankra application shiporankra application deploy, and you holdapplications.deployto change push to deploy or roll back. - For the GitOps route: the organisation has a registry connected, a GitOps repository synced to the cluster, and a token that can push to that repository.
- The CLI. v0.74.0 or later for
ankra pipeline release-queueandankra application rollback.
Build once, publish the tested image
Both routes start here. Without it, a merge builds, scans and gates the merged commit again. Withpromote_from: pull_request, a push whose tree a pull request run already tested publishes that run’s image instead:
publish needs passed there. A squash merge of a pull request that was up to date with its base has that tree; one that was behind builds in full, unless the merge train merged it, because a train car tests the merged tree. A fork’s run is never promoted. The full rules are in Promote a tested image instead of rebuilding.
With an application
1
Commit the publish stage and approve it
Add Check:
promote_from: pull_request to the application’s publish stage as above, merge it, and approve the definition:ankra pipeline get --application my-app --branch main --trigger push --latest prints Authority: approved.2
Choose which environments follow the merge
Read the application’s push to deploy switch, then decide per environment:Here staging follows every merge to
main, and production waits for an explicit deploy. In the portal the same rule is an environment’s Branches it follows: Add a branch or pattern, then Save branches. The portal says “Changing this does not deploy anything. The next push to a matching branch does.” Application environments covers patterns and other clusters.Check: the FOLLOWS column of ankra application environments my-app reads main for staging and manual for production.3
Merge a pull request and follow the release
Merge a pull request whose run passed, then wait on the push run it starts:
release-queue counts the release runs of the branch that are queued or running and names the oldest: a release behind others waits for them.Check: the push run concludes success, and its publish step’s outputs carry image_tag (sha-<7>) and image_digest. A promoted run skips its build and test stages.4
Verify the rollout
sha-<7> tag from the previous step, and production still runs its earlier tag. To ship production, run ankra application deploy with that tag, or turn push to deploy on for it.Roll back
--to the command changes nothing: it prints the tag the deployment runs, the tags it could go back to, and what a rollback does not undo (a migrated schema, data written since, changed secrets, Stack edits). With --to it asks, then puts that tag back, and holds the rollback until a newer build is observed so push to deploy does not undo it.
Without an application: a GitOps commit
A repository with no application publishes its image to the organisation’s registry as<repository>/<component>, named after the repository and the build stage (build-api gives <repository>/api). A later stage then writes the published reference into the GitOps repository, and Ankra syncs the cluster from Git.
1
Store a token for the GitOps repository
Create a secret organisation variable, here
GITOPS_TOKEN, holding a token that can push to the GitOps repository and nothing more: ankra org variables set GITOPS_TOKEN - --secret reads it from standard input. A plain variable works too, but its value is shown to everyone who can read the organisation’s variables. See Organisation secrets.A credentials binding with from: git does not fit here: its token is for the run’s own repository, not for another one.2
Add the publish and bump stages
sed expression with the line in your repository that names the image. image_ref is the full pushed reference, <repository>:<tag>, that publish-api wrote. The bump runs on pushes only, and only after publish-api succeeded. alpine/git must be inside the organisation’s image policy.Check: ankra pipeline validate reports no fatal, and lists bump-gitops as skipped for a pull request.3
Approve, merge, and follow the bump
The Check: the
secrets block is protected, so approve the definition on the default branch, then merge a pull request:bump-gitops log ends with the push to the GitOps repository, and that repository has a new commit naming the image.4
Verify the rollout
Ankra detects the commit and syncs the cluster from it (How Ankra syncs your cluster).Check: the newest operation is the sync of your commit, and the deployment’s container image is the
image_ref from the run. To roll back, revert the GitOps commit; Ankra syncs the previous image.What can go wrong
Next steps
Application environments
Branch rules per environment, and environments on other clusters.
Merge train
Test every pull request as it will merge, so every merge promotes.
pipeline.yaml reference
publish, promote_from, secrets and every other key.GitOps
How Ankra syncs a cluster from Git.