pravo promote

Quick reference

An environment whose row in $environments names others in $after takes only a release that was promoted into it, once its state is sealed (Environments). The release is the specification of the directory and the values of its tags, other than env. Its id is the fingerprint of the specification, as pravo environments shows it.

promote reads the newest note of each environment that ENVIRONMENT follows. A note is written by each apply into the state it applies, signed by whoever applied, and says which release that state runs. Reading it needs no key and no provider. When every one runs the release of this directory, promote signs a promotion that carries those notes into the state of ENVIRONMENT, and applies it there. The other tags are those of the release:

pravo apply   --env staging -t image=1.4
pravo promote prod -t image=1.4

Flags

--waive and --revoke exclude each other, and --store goes with neither --sign-only nor --revoke. The readers file of ENVIRONMENT is the one that --access-dir, PRAVO_ACCESS_DIR, $settings.access.dir of that environment or .pravo/access names, in this order. The readers file of each environment before it is the one that its own $settings.access.dir names, else .pravo/access.

When it already runs the release

When the newest note of ENVIRONMENT names the release of this directory, its apply deferred nothing, and a promotion of that release still counts there, promote says so, signs nothing, applies nothing and exits 0. To bring ENVIRONMENT back in line with the release, apply it again with pravo apply --env ENVIRONMENT. A promotion withdrawn by --revoke does not count, so after it promote signs a new one.

What is checked

Before it signs, promote checks:

An apply of ENVIRONMENT, by promote or by pravo apply, checks again, under the lock of the state: the promotion against the readers file of ENVIRONMENT, and each note it carries against the readers file of the environment it comes from, with the lineage of that state that the record holds. A promotion signed before the newest withdrawal of the release does not count. A refusal lists the commands that move the release along:

Error: prod only takes what was promoted from dev, and nobody has promoted this release yet.

Run these, skipping a step that is already done:

    pravo apply --env dev
    pravo promote prod

The plan of an environment that follows another says how its release stands, on a line that starts with Promotion:. Before a promotion it lists the same commands as the refusal of an apply. A state that is not sealed takes any release, and the plan and the apply say so on a line that starts with Environment:.

A waiver

When the state of an environment before cannot be read, an admin of ENVIRONMENT promotes with --waive "reason". The promotion is signed without the notes, holds for this release only, and its reason is written into the note of the apply, so that the environments after ENVIRONMENT see it. A writer who is not an admin is refused with exit code 5.

A withdrawal

--revoke "reason" writes a withdrawal of the release into the state of ENVIRONMENT. Every promotion of the release signed before it stops counting, and an apply is refused with the reason until a new promotion. A release that ENVIRONMENT already runs stays applied: a withdrawal stops the next apply, and a fix is a new release.

Example

One person, ada, is an admin of both environments, and one readers file serves both, which promote points out.

package estate

import (
	"pravo.dev/pravo"
	loc "pravo.dev/providers/hashicorp/local"
)

$environments: pravo.#Environments & {
	dev: {$default: true}
	prod: {$after: "dev"}
}

$settings: pravo.#Settings & {state: path: "state/\($environment.$name)"}

$local: loc.#Provider

conf: $local.#Resource.local_file & {
	filename: "\($environment.$name).conf"
	content:  "image 1.0\n"
}

Promoted to prod: dev runs this release, applied by ada less than a minute ago.
Note: dev and prod read one readers file, so a writer of dev may promote into prod. $settings.access.dir gives prod a file of its own.
Apply it there with:

    pravo apply --env prod

Promotion: dev ran this release, and ada promoted it less than a minute ago.
Apply complete! Resources: 1 added, 0 changed, 0 destroyed. [txn <id>]

With --json, promote prints one line, {"kind": "promotion", "promotion": {...}}, with the kind (promoted, waived or revoked), the environment, the fingerprint and the tags of the release, the notes it carries (from: the environment, the lineage of its state, the fingerprint, the transaction and the time of each), the time, the signer, its key and the note. The lines of the apply follow it.

Exit codes

The codes are those of Exit codes.