Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,11 @@ jobs:
RELEASE_TO: ${{ inputs.to }}
RELEASE_CUT_COMMIT: ${{ github.sha }}
RELEASE_TOKEN: ${{ steps.mint.outputs.token }}
RELEASE_EXCHANGES: ${{ github.workspace }}
- if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: release-exchanges
path: release-exchanges.json
if-no-files-found: ignore
retention-days: 90
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# 0176. The release step keeps its own exchanges, held to lists, as a public artifact of its run

Status: accepted. The Factory Builder's rulings of 2026-11-09 on the design for "The release step records its own exchanges, redacted, after factory/v0.1.0" (issue 531), which ruling 9′ of "Release: cut an immutable tag, move next, and roll back in one action" (issue 197), as amended on 2026-11-03, left open: a fixture of a Release's runs could show each run's outcome and what was read from outside it, but not what the step itself read and wrote. The edit to `.github/workflows/release.yml` was pre-approved by the Maintainer on 2026-11-08 and ruled by the Factory Builder.

## Decision

| What | Decided | Because |
|---|---|---|
| What is kept | Each exchange the step sends through `RELEASE_TOKEN`, by `release/exchanges.py`'s `Recording`, which wraps the step's one transport and passes each request through unchanged | Every read and write of the step already goes through that one object, so nothing it sends is missed and nothing it does changes |
| Held to lists | The call, its Accept where one is given, the headers `tools/check_trials.py`'s `HEADERS` lets a trial's fixture keep but `location`, and of a JSON body only the fields `FIELDS` names, at any depth, of what is sent as of what is answered; everything else is left out and its place listed in `dropped` | An artifact of a public repo can be downloaded by anyone signed in, so the file is public: what is kept is named, and nothing is kept for not being refused |
| Kept by its measure alone | An artifact's download, a file read at a commit, and any body that is not JSON: their size and sha256, never their text; a file at a commit by its own bytes, decoded from the base64 GitHub answers it in, so it can be held to the file; an answer with no body, by nothing | The download's redirect names a signed address; the eval report and the set's manifest are where a held-out case could appear; a gateway's page can quote anything |
| Then redacted | `tools/redact_trial.py`'s `redact_json`, the trials' own, over the whole file, each place it took something from listed in `removed` | One set of patterns for every capture the Factory keeps, which cannot drift; importing it starts nothing and reads nothing but modules |
| Never in the way | A fault in keeping drops that exchange and is counted in `unkept`; it never changes what the step is answered, does or prints. The file is written whatever stopped the step, in a `finally` | The step's codes and its writes are the release's evidence; a record of them must not become a way for them to fail |
| Where it goes | `RELEASE_EXCHANGES: ${{ github.workspace }}` names the folder, the checkout's root, where no commit may hold that file (`tools/check_repo.py`), so none stands there first to be uploaded in its place; the step writes the file `release/exchanges.py`'s `NAME` names there, never over one that stands; the job's last step, `if: always()`, uploads it as the one artifact `release-exchanges`, `if-no-files-found: ignore`, for 90 days; no step prints it | An expression stands only as a whole value in a workflow; 90 days is how long the eval job's `eval-report` and `eval-ledger` are kept (decision 0164), and a rollback, such as that issue's live one with v0.1.1, may come more than 30 days after a cut |
| Its form | `release-exchanges/1` (`schemas/release-exchanges.schema.json`), a record: its exchanges in the shape a `release-fixture/1` item keeps them, so a builder adds them to a fixture as they are, after redacting them again outside the repo | The fixture is where an item is held to its own exchanges (`tools/check_release.py`); the artifact is what it is made from |

## Why

Ruling 9′ of that issue keeps a fixture of each run of `.github/workflows/release.yml`, read from outside it: the run, its job's log at the step, the refs after. The step prints codes alone, so what the eval gate read, what `verify` and the comparison with `main` answered, and each write and its read-back, were seen by nothing but the step. Keeping them inside the run is the only way to see them, and the run's artifacts are public. So the design starts from what may be shown, not from what must be hidden: a field, a header or a body is kept only when a list names it, and a file's text, a signed address and an error's stray fields cannot be kept by any route but a list that does not name them.

## Boundaries

| Boundary | Check |
|---|---|
| A field no list names, a header no fixture keeps, a redirect's address, a download's or a file's text, and a body that is not JSON are left out of what the step keeps | `tests/test_release_exchanges.py::test_the_leak_surface_is_left_out`, `release/exchanges.py`; mutant: "the release step keeps a field no list names"; mutant: "the release step keeps a redirect's address"; mutant: "the release step keeps a header no fixture keeps"; mutant: "the release step keeps an artifact's download whole"; mutant: "the release step keeps a file at a commit whole"; mutant: "the release step keeps a body that is not JSON" |
| Every counter-example the trials' redaction is tested with is taken out of what the step keeps | `tests/test_release_exchanges.py::test_every_counter_example_of_the_trials_redaction_is_left_out_here`, `release/exchanges.py`; mutant: "the release step's exchanges are not redacted" |
| What `release/` imports of `tools/` starts nothing and reads nothing but modules at import | `tests/test_release_exchanges.py::test_importing_the_redaction_starts_nothing_and_reads_nothing_but_modules`, `release/exchanges.py`; mutant: "the release step's keeping starts a process at import" |
| A fault in keeping never changes what the step is answered | `tests/test_release_exchanges.py::test_a_fault_in_keeping_never_changes_what_the_step_is_answered`, `release/exchanges.py`; mutant: "a fault in keeping stops the release step" |
| It writes one file, in the folder it is given, never over one that stands | `tests/test_release_exchanges.py::test_it_writes_only_the_one_file_in_the_folder_the_workflow_names`, `release/exchanges.py`; mutant: "the release step writes over a file that stands" |
| Where a folder is named, the step keeps each exchange and prints what it printed before; where it stops or fails, it keeps what it sent | `tests/test_release_exchanges.py::test_a_cut_keeps_each_exchange_and_prints_what_it_printed_before`, `tests/test_release_exchanges.py::test_a_step_that_stops_or_fails_still_keeps_what_it_sent`, `release/move.py`; mutant: "the release step keeps nothing where a folder is named"; mutant: "a release step that fails keeps nothing" |
| `.github/workflows/release.yml`'s last step uploads the file whatever stopped the step, as the one artifact `release-exchanges`, kept 90 days, and nothing prints it | `tests/test_release_workflow.py::test_each_counter_example_is_refused_for_its_one_fault`, `tools/check_workflows.py`; mutant: "the release job uploads its exchanges only when the step succeeds"; mutant: "the release job keeps its exchanges 30 days" |
| What is sent is held to the lists as what is answered is, each field left out is named, and an answer with no body is measured by nothing | `tests/test_release_exchanges.py::test_what_is_sent_is_held_to_the_lists_too_and_each_field_left_out_is_named`, `release/exchanges.py`; mutant: "the release step keeps what it sends whole"; mutant: "the release step keeps every header it sends"; mutant: "a field the release step leaves out is not named"; mutant: "an answer with no body is measured as null" |
| A file at a commit is measured as its own bytes | `tests/test_release_exchanges.py::test_a_file_at_a_commit_is_measured_as_the_file_itself`, `release/exchanges.py`; mutant: "a file at a commit is measured as GitHub's envelope" |
| No commit holds the file the step writes at the checkout's root | `tests/test_tools.py::test_no_commit_holds_the_file_the_release_step_writes_at_the_root`, `tools/check_repo.py`; mutant: "a committed release-exchanges.json at the root passes" |
| A text, a number or a truth is kept only under a field a list names, never alone or in a list no field names; a left-out field's name is written only where it is a plain identifier | `tests/test_release_exchanges.py::test_a_value_is_kept_only_under_a_field_a_list_names`, `release/exchanges.py`; mutant: "the release step keeps a value under no named field"; mutant: "the release step names a field that could be text where it left it out"; mutant: "the release step writes an Accept it was not given"; mutant: "the release step keeps a header's name as sent" |
| A place left out is named only once its exchange is kept, and the file is written only in an absolute folder | `tests/test_release_exchanges.py::test_an_exchange_not_kept_leaves_no_place_named`, `tests/test_release_exchanges.py::test_it_writes_only_the_one_file_in_the_folder_the_workflow_names`, `release/exchanges.py`; mutant: "the release step names places of an exchange it did not keep"; mutant: "the release step writes into a relative folder" |
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
{
"schema": "release-exchanges/1",
"exchanges": [
{
"request": {
"as": {
"kind": "app",
"name": "release"
},
"via": "rest",
"call": "GET /repos/combsmith/software-factory/git/matching-refs/tags/factory",
"headers": {
"accept": "application/vnd.github+json"
},
"body": null
},
"response": {
"status": 200,
"headers": {
"content-type": "application/json; charset=utf-8",
"etag": "W/\"30eb71c9\"",
"location": "https://productionresultssa0.blob.core.windows.net/x"
},
"body": [
{
"ref": "refs/tags/factory/v0-next",
"object": {
"sha": "499835d5384ba81c466b17199edcde1848431630",
"type": "commit"
}
}
]
}
},
{
"request": {
"as": {
"kind": "app",
"name": "release"
},
"via": "rest",
"call": "GET /repos/combsmith/software-factory/actions/artifacts/9/zip",
"headers": {
"accept": "application/vnd.github+json"
},
"body": null
},
"response": {
"status": 200,
"headers": {
"content-type": "application/zip"
},
"measured": {
"size": 1024,
"sha256": "14fbe23eefd818500379b102bccdce8df98bd560f317782f90a816a8da0cb2f4"
}
}
},
{
"request": {
"as": {
"kind": "app",
"name": "release"
},
"via": "rest",
"call": "PATCH /repos/combsmith/software-factory/git/refs/tags/factory/v0-next",
"headers": {
"accept": "application/vnd.github+json"
},
"body": {
"sha": "499835d5384ba81c466b17199edcde1848431630",
"force": true
}
},
"response": {
"raised": "Unanswered"
}
}
],
"removed": [],
"dropped": [
"exchanges[0].response.body[0].node_id",
"exchanges[0].response.body[0].url"
],
"unkept": 0
}
85 changes: 85 additions & 0 deletions examples/release-exchanges.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
{
"schema": "release-exchanges/1",
"exchanges": [
{
"request": {
"as": {
"kind": "app",
"name": "release"
},
"via": "rest",
"call": "GET /repos/combsmith/software-factory/git/matching-refs/tags/factory",
"headers": {
"accept": "application/vnd.github+json"
},
"body": null
},
"response": {
"status": 200,
"headers": {
"content-type": "application/json; charset=utf-8",
"etag": "W/\"30eb71c9\""
},
"body": [
{
"ref": "refs/tags/factory/v0-next",
"object": {
"sha": "499835d5384ba81c466b17199edcde1848431630",
"type": "commit"
}
}
]
}
},
{
"request": {
"as": {
"kind": "app",
"name": "release"
},
"via": "rest",
"call": "GET /repos/combsmith/software-factory/actions/artifacts/9/zip",
"headers": {
"accept": "application/vnd.github+json"
},
"body": null
},
"response": {
"status": 200,
"headers": {
"content-type": "application/zip"
},
"measured": {
"size": 1024,
"sha256": "14fbe23eefd818500379b102bccdce8df98bd560f317782f90a816a8da0cb2f4"
}
}
},
{
"request": {
"as": {
"kind": "app",
"name": "release"
},
"via": "rest",
"call": "PATCH /repos/combsmith/software-factory/git/refs/tags/factory/v0-next",
"headers": {
"accept": "application/vnd.github+json"
},
"body": {
"sha": "499835d5384ba81c466b17199edcde1848431630",
"force": true
}
},
"response": {
"raised": "Unanswered"
}
}
],
"removed": [],
"dropped": [
"exchanges[0].response.body[0].node_id",
"exchanges[0].response.body[0].url"
],
"unkept": 0
}
4 changes: 2 additions & 2 deletions release/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,7 @@ Not built yet, by the stories that hold their rules: promote.py, cutover.py.
| A Release is cut only from a verified commit of `main`, newer than every Release, of the Channel's major | `tests/test_release.py::test_each_rule_of_a_cut_refuses_with_its_own_code` |
| `next` moves only through the eval gate, judged for that Release and read before anything is written | `tests/test_release.py::test_a_closed_eval_gate_refuses_every_cut_and_move_and_burns_no_version` |
| A step moves only a Channel the ring file declares, to a commit one Release names alone | `tests/test_release.py::test_only_a_channel_the_ring_file_declares_is_moved`, `tests/test_release.py::test_a_channel_moves_only_to_a_commit_one_release_names_alone` |
| No step writes a Release tag | `tests/test_release.py::test_no_step_writes_a_release_tag_and_none_names_anything_but_a_channel` |
| No step moves `stable` until promotion is built | `tests/test_release.py::test_stable_is_never_moved_until_promotion_is_built` |
| No step writes a Release tag, or moves `stable` until promotion is built | `tests/test_release.py::test_no_step_writes_a_release_tag_and_none_names_anything_but_a_channel`, `tests/test_release.py::test_stable_is_never_moved_until_promotion_is_built` |
| A rollback passes no gate and moves only back | `tests/test_release.py::test_a_rollback_passes_no_gate_and_never_moves_forward` |
| By default it moves to the greatest Release below | `tests/test_release.py::test_a_rollback_by_default_takes_the_greatest_release_below_the_one_next_is_on` |
| A commit's Release is its one Release tag; a Channel never is one, and two are none | `tests/test_release.py::test_a_commit_with_no_release_or_two_resolves_to_none` |
Expand All @@ -38,3 +37,4 @@ Not built yet, by the stories that hold their rules: promote.py, cutover.py.
| Only `.github/workflows/release.yml` runs the step, held to its shape: one job on `factory-release`, its token for this repo alone, no checkout an output names | `tests/test_release_workflow.py::test_each_counter_example_is_refused_for_its_one_fault` |
| No other workflow names the release job's environment, key, token or step | `tests/test_release_workflow.py::test_only_release_yml_names_the_release_jobs_environment_key_token_or_step` |
| A cut asked with no version, as the schedule asks one, is of the next patch of its major | `tests/test_release_workflow.py::test_a_cut_asked_with_no_version_is_of_the_next_patch_or_the_majors_first` |
| The step keeps its exchanges held to lists and redacted, never changing what it does | `tests/test_release_exchanges.py::test_the_leak_surface_is_left_out`, `tests/test_release_exchanges.py::test_a_step_that_stops_or_fails_still_keeps_what_it_sent` |
Loading
Loading