Skip to content

Auto promotion

By default, a build is promoted explicitly, by associating a promotion with it.

By configuring an auto promotion on a promotion level, a build is promoted automatically as soon as a given list of validations has passed, and a given list of other promotions has been granted, on that build.

For example, a build which has passed integration tests on platforms A, B and C can be promoted automatically, without anyone having to do it by hand.

Auto promotion is configured by setting the "Auto promotion" property on a promotion level.

Note

A validation counts as passed when the status of its last run is PASSED or FIXED — a validation which failed and was later fixed counts towards the auto promotion.

A CHML validation stamp can also opt in, with warningPassesAutoPromotion, to having a last run in WARNING status count as passed. This applies to the auto promotion only — a WARNING run still shows as a warning everywhere else — and only to a last status of exactly WARNING: a warning later moved to another status, INVESTIGATING or EXPLAINED for example, does not count. With this option, a WARNING run both promotes a build and leaves an auto revoked promotion standing.

Selecting the validations

The list of validation stamps can be defined by:

  • selecting a fixed list of validation stamps
  • selecting them by name, using the include and exclude regular expressions

Warning

A validation stamp named explicitly in the list is always taken into account, whatever the include and exclude regular expressions say.

The list of promotion levels which must be granted is set independently of the list of validations.

Seeing the conditions

A promotion level with an auto promotion carries a ⚡ next to its name. Hovering it lists the conditions: the validation stamps actually required on the branch — the ones named explicitly, plus the ones matching include and not exclude — the required promotions, and the regular expressions when they are set.

Hovering a promotion of a build, in the branch builds view or on the build page, shows the same conditions under Auto promotion conditions, with their state for that build:

  • the status of the last run of each required validation, linking to that run, or Not run
  • each required promotion, linking to its last run on the build, or Not granted
  • a summary line, for example 2/3 validations passed · 1/1 promotion granted

A WARNING run accepted by its CHML validation stamp counts as passed in the summary line, but its row still shows the WARNING status, so that the tolerance stays visible.

On the build page, hovering a promotion the build does not have yet shows the same conditions, with their state for that build, under the promotion's name marked Not granted — the place to look when wondering why a build is not promoted. A promotion level without auto promotion shows its description only.

These are the current conditions and statuses. The auto promotion property is not versioned, so they explain why the build is — or is not — promoted today, not what triggered a promotion in the past. They are shown for manually granted promotions too.

The GraphQL API exposes them as the autoPromotionConditions field of PromotionLevel and of PromotionRun, and as the autoPromotionConditions(promotionLevelId) field of Build, for any promotion level of the build's branch, granted or not.

Revoking a promotion

By default, a promotion which has been granted stays granted, even if the validations which triggered it later fail.

Enabling "Revoke the promotion when a prerequisite is no longer valid" on the auto promotion property revokes the promotion as soon as one of its prerequisites — a required validation stamp or a required promotion — stops being valid.

This is opt-in and disabled by default.

Warning

Revoking a promotion deletes it, but does not undo its effects: any notification or workflow already triggered by the promotion remains fired.

Deleting the promotion run removes the promotion, not the auto-versioning pull requests it opened, the notifications it sent, or the workflows it started.

Note

Enabling the option does not re-evaluate the builds which are already promoted. Revocation is forward-looking: it reacts only to a prerequisite actually becoming invalid from that point on.

Behaviours worth knowing

Three consequences surprise people:

Manual deletions cascade. A prerequisite is no longer valid whoever made it untrue. Deleting a BRONZE promotion by hand also deletes every downstream promotion which required it and has the option enabled, in the same click. This is also what makes "undo a mis-promotion" work down the whole chain.

A newly added prerequisite which fails revokes an old promotion. If a validation stamp matching the include regular expression is added, and a run for it later fails on a build which was already promoted, that promotion is revoked. Nothing happens when the property is edited — only when a real failing run appears.

Every run of the promotion level is revoked, including the ones created manually. Enabling the option declares the promotion level fully auto-managed; leaving a manual run standing would show the build as promoted while its prerequisites are red.

Being notified

A revocation posts an auto_promotion_revoked event, in addition to the delete_promotion_run event for the run itself. The first says why the promotion is gone, the second says that it is.

Subscribe to auto_promotion_revoked to be told about automatic revocations specifically, as opposed to a person deleting a promotion.

Configuration as code

Auto promotion can also be set through the CI configuration, using the validations, promotions and autoRevoke keys of a promotion.