User Story
As a developer testing an agent integration with OpenShell development builds, I want to record exactly which CLI, gateway, sandbox and supervisor artifacts belong to the build I am using, so that I can repeat a test and tell a maintainer what I actually ran.
Problem Statement
OpenShell publishes downloadable binaries and container images. It already provides archive checksums and image provenance, but there is no single published record connecting the core binaries and images to the same source commit and build run. Users have to assemble that information from separate sources. The build architecture documents the existing artifact and image safeguards.
The rolling dev release also changes over time. Its publication workflow replaces release assets and moves the tag. Recording only “tested with dev” is therefore insufficient to identify the files used in a test.
Impact / Why This Matters
During our integration work, the development release advanced while we were checking whether a fix was available. We had to recheck the source revision and release asset identity, and maintain separate records for the runtime artifacts. That is the concrete motivation here: manual verification and record keeping around a moving release. We have not established that accidentally mixing release components caused a failure.
A developer who downloads a CLI and runs OpenShell containers needs to preserve enough information for a colleague to select the same artifacts later. A shared release record would also make bug reports more precise: the maintainer could identify the build without asking the reporter to reconstruct it from downloads and workflow logs.
Proposed Design
Publish a machine-readable record alongside each development build, covering the standalone core archives and the container images for the gateway, sandbox and supervisor.
The user workflow would be:
- Save the record with the integration's test results.
- Check downloaded archives against its checksums and select container images by their content digests, which identify exact image contents.
- Share the record when reporting a problem or repeating the test, so the source commit, build run and platform are explicit.
PR #3445's proposed installation guidance describes this as openshell-release-manifest.json, with an attestation identifying its producer. Inconsistent or incomplete inputs should stop publication before existing development release assets are replaced.
Acceptance Criteria
Alternatives Considered
- Record only the version or
dev tag. This does not identify all of the exact artifacts used.
- Collect checksums, image digests and build metadata manually. This is possible today, but every integration has to assemble and maintain the association itself.
- Rebuild from a source commit. That provides a local build, but does not identify the published artifacts used in the original test.
Agent Investigation
Reviewed the public release workflow, build documentation and PR changes, and searched related issues. Issue #2946 asks for broader reuse of immutable artifacts across CI and packaging. This proposal covers the release identity record; it does not implement that issue's cross-workflow resolver or make all tests and packages consume the same artifacts. No new runtime or release-publication tests were run for this issue draft.
Checklist
User Story
As a developer testing an agent integration with OpenShell development builds, I want to record exactly which CLI, gateway, sandbox and supervisor artifacts belong to the build I am using, so that I can repeat a test and tell a maintainer what I actually ran.
Problem Statement
OpenShell publishes downloadable binaries and container images. It already provides archive checksums and image provenance, but there is no single published record connecting the core binaries and images to the same source commit and build run. Users have to assemble that information from separate sources. The build architecture documents the existing artifact and image safeguards.
The rolling
devrelease also changes over time. Its publication workflow replaces release assets and moves the tag. Recording only “tested with dev” is therefore insufficient to identify the files used in a test.Impact / Why This Matters
During our integration work, the development release advanced while we were checking whether a fix was available. We had to recheck the source revision and release asset identity, and maintain separate records for the runtime artifacts. That is the concrete motivation here: manual verification and record keeping around a moving release. We have not established that accidentally mixing release components caused a failure.
A developer who downloads a CLI and runs OpenShell containers needs to preserve enough information for a colleague to select the same artifacts later. A shared release record would also make bug reports more precise: the maintainer could identify the build without asking the reporter to reconstruct it from downloads and workflow logs.
Proposed Design
Publish a machine-readable record alongside each development build, covering the standalone core archives and the container images for the gateway, sandbox and supervisor.
The user workflow would be:
PR #3445's proposed installation guidance describes this as
openshell-release-manifest.json, with an attestation identifying its producer. Inconsistent or incomplete inputs should stop publication before existing development release assets are replaced.Acceptance Criteria
Alternatives Considered
devtag. This does not identify all of the exact artifacts used.Agent Investigation
Reviewed the public release workflow, build documentation and PR changes, and searched related issues. Issue #2946 asks for broader reuse of immutable artifacts across CI and packaging. This proposal covers the release identity record; it does not implement that issue's cross-workflow resolver or make all tests and packages consume the same artifacts. No new runtime or release-publication tests were run for this issue draft.
Checklist