Skip to content

Gate a deploy on the command health check and receipt it (S-009-2..9, 11, 12) #164

Closed

Description

@shipmill-romamo

Builds part of spec S-009, docs/specs/009-command-health-check.md (feature issue #152): the acceptance criteria below. Each needs a test that names its id (test_s009_<k>_..., or a proves: S-009-2 comment line).

This is the command check in the deploy's health gate, its rescue, and the release receipt's healthCheck.

  • S-009-2: The command check runs after the Switch the current release symlink and Restart the component service tasks, inside the block whose rescue restores the previous release, as the application's linuxUser, with working directory <installRoot>/current, the service unit's EnvironmentFile=- line and RuntimeMaxSec= equal to timeoutSeconds
  • S-009-3: A relative first element of command runs as <installRoot>/current/<element>, and an absolute one runs unchanged
  • S-009-4: A command check that exits 0 lets deploy --yes exit 0 with a receipt carrying healthCheckPassed: true and healthCheck with the command, attempts: 1, exitCode: 0 and timedOut: false
  • S-009-5: A command check that exits 3 on every attempt makes deploy --yes exit ENGINE_STEP_FAILED with an error.message naming the command health check and exit code 3; afterwards current points at the previous release, the service was restarted on it, and the receipt at <releases>/<component>.json validates against the schema with healthCheckPassed: false, healthCheck.exitCode: 3, release the failed release and previousRelease the restored one
  • S-009-6: The same failure on a first release stops the service and writes a receipt with healthCheckPassed: false and previousRelease: null
  • S-009-7: A run still going after timeoutSeconds is stopped and counts as a failed attempt; when the last attempt timed out, the deploy fails the same way, the error.message names the timeout, and the receipt has timedOut: true and exitCode: null
  • S-009-8: A check that fails twice and then passes with attempts: 3 passes and records attempts: 3; a check that always fails runs exactly attempts times, 3 seconds apart
  • S-009-9: A check that prints a marker string on stdout and stderr and exits 1 leaves the marker in neither the receipt, the ansible-playbook output nor the deploy error, and the receipt schema refuses a healthCheck with any key besides type, command, attempts, exitCode and timedOut
  • S-009-11: The receipt schema refuses healthCheckPassed: false without a command healthCheck, or with exitCode: 0, and still accepts every receipt the deploy writes today
  • S-009-12: Components with type: http and type: none run the same gate tasks as before, their receipts have no healthCheck key, and a failed http or none gate writes no receipt

Depends on #161

Activity

  1. shipmill-romamo commented on Oct 30, 2026

    @shipmill-romamo
    ContributorAuthor

    Triage: implement. Serves: G-3. A build issue of spec S-009 (docs/specs/009-command-health-check.md, approved in #153), sub-issue of #152. The criteria above are the scope; each gets a test naming its id. It starts once every issue on its Depends on line has closed.

  2. shipmill-romamo commented on Oct 30, 2026

    @shipmill-romamo
    ContributorAuthor

    The build is in #180: a type: command health check gates deploy --yes, run after the switch and restart inside the rescue block, in a transient unit with the command as an argv list; its output stays in the server journal. A failed check rolls back (or stops a first release), writes the receipt with healthCheckPassed: false and its healthCheck, and fails the deploy naming the exit code or the timeout. http and none checks run as before.

    Trade-offs: the receipt schema is a little stricter than S-009-11's text (a passing healthCheck must have exitCode: 0 and timedOut: false, a timeout needs exitCode: null); every receipt written today still validates. Unverified: systemd-run was a stand-in in the tests, so the real timeout output wants a live run. restart, rollback and health still refuse a command check until #166.

    This issue closes when #180 merges.

  3. added a commit that references this issue on Oct 30, 2026
    3cc2c78
  4. shipmill-romamo commented on Oct 30, 2026

    @shipmill-romamo
    ContributorAuthor

    Released in v0.8.0rc12 (pre-release).
    A plain install gets it with the next stable release.
    If you filed this: react 👍 on this comment once it works for you, or reply if it doesn't.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions