CLI command

probierz gate stage

Judge one release of a product as it was installed into an account of its own: run the targets its release policy requires there, sign the receipt and evaluate the release gate on those runs, in one answer.

Invocation#

Shell
probierz gate stage <appId> --source <dir> --source-commit <sha> --release <id> --home <dir> [--record]

Required inputs and options#

  • <appId> is the product; --source is the released source tree, exported or checked out, whose .probierz/<appId>.yaml is the manifest read and whose .probierz/<appId>/ holds the journeys that run. The tree need not be a git checkout: the delivery that stages a release holds an export of it, and --source-commit (40 hexadecimal digits) is the commit it was exported from, stated in the evidence beside the tree's own path-independent SHA-256.
  • --release is the release judged, as its receipt and the release gate name it. --home is the account the release was installed into: every journey runs with HOME set to it and PATH beginning with its .stado/bin, .local/bin and bin, so the journeys use the installed release and nothing of the account Probierz runs under.
  • The manifest's releasePolicy decides what runs and what passes: each target of requiredTargets runs once with its required journeys, and the gate applies the policy's minimumEvidence and every other check gate evaluate applies. --record keeps video, traces and screenshots of every journey, as for run.
  • The receipt is signed with the Ed25519 key PROBIERZ_RECEIPT_PRIVATE_KEY_FILE names, as for receipt create.

Output and state effects#

Makes its staging workspace, then runs each of Probierz's own commands in it: probierz identity <appId>, each required target as probierz run <target> --app <appId> --no-repair does (a failed run opens or joins its defect and starts no repair) with HOME and PATH as above, keeping each run under test-results/<appId>/<target>/; one receipt over those runs as receipt create signs it under test-results/receipts/<appId>/<release>/; and the release gate on them as gate evaluate judges it. Answers {schemaVersion: 1, appId, release, sourceCommit, sourceSha256, harnessSha256, home, workspace, runs: [{runId, target, passed, evidence}], receipt: {path, passed}, verdict: {passed, errors, gate}} as JSON, verdict.gate being the gate's own verdict whole. Exits 0 only when every required target passed, the receipt passed and the gate is green; a red verdict is printed whole and exits 1.

Exact refusals#

  • Each before anything runs, and no run or receipt is kept (probierz.gate.stage): stage-arguments-missing (exit 2), naming each of <appId>, --source, --source-commit, --release and --home not given; stage-commit-invalid (exit 2), a --source-commit that is not 40 hexadecimal digits; stage-source-unreadable (exit 1), a --source that is no directory this account can read, naming it and the system's answer; stage-manifest-missing (exit 1), a source tree with no .probierz/<appId>.yaml, naming the path looked for; stage-home-missing (exit 1), a --home that is no directory, naming it.
  • policy-missing and manifest-invalid (exit 1) as for gate evaluate; stage-targets-none (exit 1): a release policy that requires no target, since a staging that runs nothing proves nothing, naming the manifest and releasePolicy.requiredTargets.
  • signing-key-missing, signing-key-unreadable, signing-key-invalid (exit 1) as for receipt create, refused before any target runs, so no run is made that could not be signed.
  • stage-workspace-unmade (exit 1): the staging workspace under test-results/<appId>/stage/<started>/ — the export copied as the checkout the manifest names, committed once so its manifest is tracked, and a state holding this instance's configuration with workspace naming it — could not be made, naming the step (its directories, the copy, the commit, the configuration) and the system's answer; nothing is run or signed.
  • stage-step-failed (exit 1): a step gave no answer to judge — a required target refused before it ran (its preflight, not-placed for documentation examples outside a Stado job, …), the source identity, the receipt or the gate — naming the command, how it ended and the last lines it said; the runs already made are kept and named.
  • verdict-red (exit 1): a run that failed, a receipt whose evidence did not pass or a gate the evidence does not meet; the answer is printed with every error.
  • Real test: tests/gate/stage.rs.

Declared refusals#

What probierz refusals list declares for this command at revision d2cd6156e8b8dc6204dab7b46ec0b34b2bb03cea (probierz 0.1.7 (revision unknown, not built from a git checkout)): each cause's id, the operation declaring it, its exit status and code, and its remedy.

  • variable-blank (probierz.harness, exit 1, config): finding the harness PROBIERZ_HARNESS_DIR names: PROBIERZ_HARNESS_DIR is set but blank, so it names no directory. set PROBIERZ_HARNESS_DIR to the Probierz checkout that holds packages/, or unset it so the checkout the binary was built in, the working directory and the installed harness are tried.
  • no-packages (probierz.harness, exit 1, config): finding the harness every command but the instance's configuration reads: {searched} holds no packages/ directory, so there are no journey runners to run. pass --harness, or set PROBIERZ_HARNESS_DIR, to a Probierz checkout that holds packages/, or unset both so the installed harness in Probierz's state directory is used.
  • packages-unexaminable (probierz.harness, exit 1, config): examining {path} for the harness: the operating system would not say what {path} is: {error}. give this user search permission on the directory that holds {path}, or name another checkout with --harness.
  • installed-unwritable (probierz.harness, exit 1, config): writing the runners this binary carries into the installed harness {root}: {path} could not be written: {error}. make {root} a directory this user can write (PROBIERZ_STATE_DIR moves Probierz's state directory), or name a checkout with --harness.
  • actor-missing (probierz.records.actor, exit 1, config): attributing a record to who made it: no actor to attribute this record to: PROBIERZ_ACTOR, GITHUB_ACTOR and USER are all unset or empty. set PROBIERZ_ACTOR to the person or agent making the record.
  • actor-not-text (probierz.records.actor, exit 1, config): attributing a record to who made it: {variable} is set but is not UTF-8 text, so it cannot name who made the record. set {variable} to the actor's name in UTF-8, or unset it.
  • json-unreadable (probierz.records.json, exit 1, config): reading {file}: the file cannot be read: {error}. make {file} readable to this user.
  • json-malformed (probierz.records.json, exit 1, config): reading {file}: the file does not hold JSON: {error}. write {file} again as the command that made it does, or remove it.
  • json-missing (probierz.records.json, exit 1, not_found): reading {file}: no file is there, and the command needs it. name a file that is there.
  • run-unknown (probierz.records.run, exit 1, not_found): reading run {run} of {app}: no run of that id is recorded for {app}. name a run probierz history {app} lists.
  • run-record-incomplete (probierz.records.run, exit 1, config): reading when the run recorded at {file} expires: the run record {problem}. a run Probierz records states its kind and when it started and completed as RFC 3339 times: restore the record from its bundle with probierz restore, or name its kind after the run id where the command takes one (probierz protect <appId> <runId> <kind>).
  • receipt-arguments-missing (probierz.receipt.create, exit 2, refused): signing a receipt: {missing} must be given. give every one: probierz receipt create <appId> <release> <harnessSha256> --source-sha <sha256> --runs <id,...> --minimum E<n>.
  • receipt-sha-invalid (probierz.receipt.create, exit 2, refused): signing a receipt: {name} {value} is no lowercase SHA-256. give the 64 lowercase hexadecimal digits of the source's SHA-256, as the runs' source identity states it.
  • receipt-runs-missing (probierz.receipt.create, exit 2, refused): signing a receipt: --runs names no run. name each run the receipt signs, comma-separated, as probierz history lists them.
  • receipt-minimum-invalid (probierz.receipt.create, exit 2, refused): signing a receipt: {problem}. give --minimum as the release policy states it: E followed by its rank, such as E2.
  • signing-key-missing (probierz.receipt.create, exit 1, config): signing a receipt: PROBIERZ_RECEIPT_PRIVATE_KEY_FILE is not set, so no key can sign it. set PROBIERZ_RECEIPT_PRIVATE_KEY_FILE to the issuer's Ed25519 private key file, PKCS#8 PEM or DER.
  • signing-key-unreadable (probierz.receipt.create, exit 1, config): signing a receipt: the signing key {key} cannot be read: {error}. point PROBIERZ_RECEIPT_PRIVATE_KEY_FILE at a key file the user running Probierz can read.
  • signing-key-invalid (probierz.receipt.create, exit 1, config): signing a receipt: the signing key {key} is no Ed25519 private key: {error}. point PROBIERZ_RECEIPT_PRIVATE_KEY_FILE at the issuer's Ed25519 private key, PKCS#8 PEM or DER.
  • public-key-unencoded (probierz.receipt.create, exit 69, infra_down): writing the Ed25519 public key of a receipt as {encoding}: the key encoder could not write the 44-byte document an Ed25519 key is. run the command again on a host with free memory: the encoder fails only when it cannot allocate.
  • directory-uncreatable (probierz.evidence.files, exit 1, config): making the directory {directory} for {what}: it cannot be created: {reason}. give this user write permission on the nearest existing parent of {directory}, or move a file standing in its path out of the way.
  • file-exists (probierz.evidence.files, exit 1, config): writing {what} to {file}: a file is already at {file}; evidence is never overwritten. move {file} out of the way if it is not the evidence you mean to keep, or keep it and write elsewhere.
  • file-unwritable (probierz.evidence.files, exit 1, config): writing {what} to {file}: it cannot be written: {reason}. give this user write permission on the directory of {file}, and free space on its disk.
  • mode-unset (probierz.evidence.files, exit 1, config): making {file} private to this user (mode {mode}): its permissions cannot be changed: {reason}. make this user the owner of {file}, then chmod {mode} {file}.
  • segment-empty (probierz.evidence.files, exit 2, refused): filing the evidence under its {what}: the {what} {value} holds no letter or digit, so it names no directory of its own. give a {what} with at least one letter or digit.
  • unreadable (probierz.evidence.hash, exit 1, config): hashing {file}: the file cannot be read: {reason}. give this user read permission on {file}, or restore it from its bundle.
  • verdict-failed (probierz.verdict, exit 1, refused): {point}: the run completed and its verdict at {verdict} is false, blocked by {blockers}. read the result's blockers, errors or reason: each names what to fix in the artifact, the product or the declaration, then run the command again.
  • verdict-missing (probierz.verdict, exit 1, refused): {point}: the result states no boolean verdict at {verdict}, so whether it passed is unknown. this is a defect of the command that produced the result: report it with the result shown.
  • source-identity-invalid (probierz.identity, exit 1, config): reading the source identity PROBIERZ_SOURCE_IDENTITY names: {file} {problem}. point PROBIERZ_SOURCE_IDENTITY at the source-identity.json a Stado job was given, as probierz identity <app> writes it, or unset it to identify the checkouts on this host.
  • root-unnamed (probierz.identity, exit 1, config): naming the repository at {root}: {root} ends in no directory name, and the identity names each repository by it. declare the repository by its checkout's directory name under the workspace.
  • git-unstarted (probierz.identity, exit 1, config): listing the files of {root} with {line}: git could not be started: {reason}. install git, or put the directory that holds it on PATH.
  • git-refused (probierz.identity, exit 1, config): listing the files of {root} with {line}: git {ended}, so the files of {root} are not known. make {root} a git checkout git can read (git -C {root} status names what it refuses).
  • file-unreadable (probierz.identity, exit 1, config): hashing {file} of {root}: git lists the file and it cannot be read: {reason}. give this user read permission on {file}, or remove it from the checkout.
  • workspace-unset (probierz.manifest.discover, exit 1, config): finding the repositories that hold product manifests: this instance names no workspace, so there is no directory of repositories to look in. run probierz config set workspace <directory holding one checkout per repository>.
  • workspace-unreadable (probierz.manifest.discover, exit 1, config): listing {workspace}: the operating system would not list it: {error}. give this user read permission on {workspace}, or set another workspace with probierz config set workspace.
  • listing-failed (probierz.manifest.discover, exit 1, config): asking the git of {repository} which manifests it tracks: {cause}. make {repository} a git repository this user can read.
  • untracked (probierz.manifest.discover, exit 1, config): reading the manifests of {repository}: {file} is not tracked by the repository's git, so no other host and no review sees it. run git -C {repository} add {relative} and commit it, or remove the file.
  • duplicate (probierz.manifest.discover, exit 1, config): finding the manifest of {app}: two repositories declare {app}: {first} and {second}. keep the manifest of {app} in the product's own repository and remove the other.
  • not-found (probierz.manifest.discover, exit 1, config): finding the manifest of {app}: no repository under {workspace} has .probierz/{app}.yaml. add .probierz/{app}.yaml to the product's repository (probierz project adopt or probierz author manifest write it), or name an app probierz apps list lists.
  • file-name-invalid (probierz.manifest.discover, exit 1, config): finding the manifests of {repository}: {file} names app "{app}", which is not an id: letters, digits, '.', '_' and '-', starting with a letter or digit. rename it .probierz/<appId>.yaml with the id it declares, with git mv.
  • repository-name-invalid (probierz.manifest.discover, exit 1, config): finding repository "{name}" in the workspace: a manifest names a checkout directly under the workspace, and "{name}" would name another place. name the checkout by its directory name under the workspace in repositories[].repository.
  • app-id-invalid (probierz.manifest.load, exit 2, refused): naming an app: "{app}" is not an id: letters, digits, '.', '_' and '-', starting with a letter or digit. name an app probierz apps list lists.
  • manifest-unreadable (probierz.manifest.load, exit 1, config): reading {file}: {error}. write {file} as YAML the reader accepts (its line and column are named), then load it again.
  • manifest-invalid (probierz.manifest.load, exit 1, config): judging {file}: {problem}. fix the declaration in {file}; probierz app check names every problem it has with the world once it loads.
  • manifest-id-mismatch (probierz.manifest.load, exit 1, config): loading the manifest of {app}: {file} is named for {app} and declares appId {declared}. declare appId: {app} in {file}, or rename the file for the app it declares with git mv.
  • mode-invalid (probierz.gate.evaluate, exit 2, refused): evaluating a gate: {mode} is no gate mode. name pull-request, which evaluates the manifest's pullRequestPolicy, or release, which evaluates its releasePolicy.
  • policy-missing (probierz.gate.evaluate, exit 1, config): evaluating the {mode} gate of {app}: {key} is missing from {file}. declare {key} in {file}: the minimumEvidence it requires (E2 or E3), and the targets, journeys and matrix profile its runs must cover.
  • verdict-red (probierz.gate.evaluate, exit 1, refused): evaluating the {mode} gate of {app}: the evidence offered does not meet its policy: {errors}. offer runs that meet each error the verdict names: made with the expected harness from the expected source, covering the targets, journeys and evidence level the policy requires.
  • stage-arguments-missing (probierz.gate.stage, exit 2, refused): judging a staged release: {missing} not given: a staged release is judged only for an exact source, commit, release and account. give each: probierz gate stage <appId> --source <dir> --source-commit <sha> --release <id> --home <dir>.
  • stage-commit-invalid (probierz.gate.stage, exit 2, refused): judging {app} {release} as staged: --source-commit {commit} is not a commit: it must be 40 hexadecimal digits. give the full commit the released source was exported from (the delivery's WISENT_SOURCE_COMMIT).
  • stage-source-unreadable (probierz.gate.stage, exit 1, config): judging {app} {release} as staged: the released source {source} cannot be read: {error}. name with --source the directory the release's source was exported into, readable by the account Probierz runs as.
  • stage-manifest-missing (probierz.gate.stage, exit 1, config): judging {app} {release} as staged: the released source declares no manifest of {app}: {manifest} is not there. commit .probierz/{app}.yaml with its releasePolicy to the product's repository, release it again, or name the product the source declares.
  • stage-home-missing (probierz.gate.stage, exit 1, config): judging {app} {release} as staged: the account {home} the release was installed into is not a directory. name with --home the home the release's installer ran under (the staging account a delivery made).
  • stage-targets-none (probierz.gate.stage, exit 1, config): judging {app} {release} as staged: {manifest} declares a releasePolicy whose requiredTargets name no target, and a staging that runs nothing proves nothing. name in releasePolicy.requiredTargets each target whose journeys use the installed release as its users do.
  • stage-workspace-unmade (probierz.gate.stage, exit 1, config): judging {app} {release} as staged: the staging workspace {workspace} could not be made ({step}): {error}. free {workspace} under the harness's test-results, writable by the account Probierz runs as, and stage again.
  • stage-step-failed (probierz.gate.stage, exit 1, refused): judging {app} {release} as staged: {step} gave no answer to judge ({ended}): {said}. settle what {step} names (a target's preflight, a source identity, a receipt) and stage again.

Source snapshot#

Generated from the Rust binaries at revision 99a74945a3598a8d73b6c6cbe5aae4f283becea3 of Probierz's private source repository.

Combined help SHA-256: 77529678a61237f774b59e76df0d1907cb749ef5da56d2ed913b040793b7d30b; binary SHA-256: be9e0eaff0e6ea50403a0c6f6d467697a4eac676f9523b8dc13a596d2b5526c5.