IMPORTANT: Developer documentation for the current development branch. This content is unreleased, may change without notice, and must not be treated as Buildish release documentation.

Harness scenario and runtime result types

Harness scenario inputs, mocked tool behavior contracts, and machine-readable run results.

Harness scenario inputs, mocked tool behavior contracts, and machine-readable run results.

Back to the reference overview.

Type index

FileWriteAction

A file write that a mocked tool invocation should perform.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
path str yes Filesystem path, relative artifact path, or retained evidence path associated with the related record.
content str yes Literal file content that the harness should write or that the mocked tool should emit.
executable bool no Whether the written file should have the executable bit set in the harness workspace.

GitRepositoryFixture

A disposable Git repository that should be initialized inside the workspace.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
path str yes Filesystem path, relative artifact path, or retained evidence path associated with the related record.
default_branch str no Branch name that the harness should create as the default branch in the disposable Git repository fixture.
commit_message str no Commit message that the harness should use when creating the initial commit in the disposable Git repository fixture.
files list[WorkspaceFile] no Workspace files that the harness should create inside the related fixture repository before execution begins.

HarnessBuiltinGhRelease

Synthetic GitHub Release retained by the stateful harness shim.

  • category: runtime
  • ownership: runtime-derived
  • file contract: (inner type)
Field Type Required Description
id int yes Synthetic GitHub Release identifier.
repository str yes GitHub repository identity associated with the release.
tag_name str yes Exact tag associated with the release.
name str yes Release title.
body str yes Release body.
draft bool yes Whether the release remains a draft.
prerelease bool yes Whether the release is a prerelease.
html_url str yes Synthetic browser-facing release URL.
url str yes Synthetic API-facing release URL.
assets list[HarnessBuiltinGhReleaseAsset] no Synthetic assets currently attached to the retained GitHub Release.

HarnessBuiltinGhReleaseAsset

Synthetic GitHub Release asset retained by the stateful harness shim.

  • category: runtime
  • ownership: runtime-derived
  • file contract: (inner type)
Field Type Required Description
id int yes Synthetic GitHub Release asset identifier.
name str yes Release asset basename.
size int yes Release asset size in bytes.
digest str yes GitHub-style algorithm-prefixed asset digest.
stored_path str yes Workspace-relative path containing the retained bytes.

HarnessBuiltinGhTagObject

Synthetic GitHub tag-object payload retained by the harness shim.

  • category: runtime
  • ownership: runtime-derived
  • file contract: (inner type)
Field Type Required Description
tag str no Tag name associated with the related release, workflow fixture, or synthetic GitHub tag-object payload.
message str no Human-readable message body associated with the related verification failure, harness tag object, or fixture definition.
object str no Git object SHA that the synthetic annotated-tag payload ultimately points at.

HarnessCommandTraceEntry

One persisted command-trace entry recorded by harness tool shims.

Field Type Required Description
tool str yes Tool name associated with the recorded harness command trace entry.
argv list[str] no Exact argv list that the harness should match or that it recorded for the related command invocation.
cwd str yes Working directory that the harness should use or that it observed for the related command invocation.
env dict[str, str] no Environment-variable mapping supplied to the related build, scenario, or command step.
exit_code int yes Process exit code that the harness recorded or should synthesize for the related tool invocation.
stdout str no Captured stdout that the harness recorded or should synthesize for the related tool invocation.
stderr str no Captured stderr that the harness recorded or should synthesize for the related tool invocation.
delegated bool no Whether the recorded harness command invocation delegated to the real tool implementation.

HarnessInspectablePaths

Stable inspectable workspace paths exposed by the harness CLI.

  • category: runtime
  • ownership: runtime-derived
  • file contract: (inner type)
Field Type Required Description
workspace_root str yes Filesystem path of the harness workspace root used by the persisted shim state.
primary_git_checkout str yes Harness workspace path of the primary repository checkout used for the workflow-under-test.
rewritten_workflows str yes Harness workspace path that contains workflow YAML files rewritten for local execution.
harness_root str yes Harness workspace path that contains persisted harness state, rewritten workflows, and generated helper files.
generated_actions str yes Harness workspace path that contains generated helper scripts or wrapper actions.
repo_sources str yes Harness workspace path that contains repository source templates or seed inputs used to build fixture checkouts.
git_origins str yes Harness workspace path that contains the origin repositories used to seed local Git checkouts.
self_git_origin str yes Harness workspace path of the local Git origin repository used to simulate GitHub-side mutations for the primary repository.
git_checkouts str yes Harness workspace path that contains generated Git working-copy checkouts.
svn_root str yes Harness workspace path that contains all simulated SVN repository and working-copy state.
svn_repository str yes Harness workspace path that contains the simulated backing SVN repository state.
svn_working_copy str yes Harness workspace path of the simulated SVN working copy used during the run.
step_summaries str yes Harness workspace path that contains per-step summary files emitted during the run.
job_summaries str yes Harness workspace path that contains one rendered markdown or text summary per job.
job_statuses str yes Final per-job status map emitted by the harness for the reported workflow or sequence run.
command_trace str yes Harness workspace path of the structured command-trace log emitted during the run.

HarnessRunResultJson

Machine-readable JSON payload for one harness run or rerun.

Field Type Required Description
workspace str yes Filesystem path of the harness workspace directory for the related run.
inspectable_paths HarnessInspectablePaths yes Paths that a harness caller can inspect after the run to understand rewritten workflows, summaries, and persisted state.
selected_job_ids list[str] no Harness job ids selected for execution in the reported run.
failed_job_ids list[str] no Harness job ids that finished with a failure outcome in the reported run.
blocked_job_ids list[str] no Harness job ids that were not run because an upstream dependency failed or was blocked.
job_statuses dict[str, HarnessJobStatus] no Final per-job status map emitted by the harness for the reported workflow or sequence run.

HarnessScenario

A runner-agnostic integration-test scenario.

  • category: authored
  • ownership: consumer-owned
  • schema file: harness-scenario.schema.json
  • audience: internal
  • stability: stable
  • file contract: harness/scenarios/*.yaml
Field Type Required Description
name str yes Stable name for the related object, branch, tag, release, or harness step.
backend HarnessBackendName no Execution backend name that performed the related Buildish action or reproducibility run.
env_capture list[str] no Environment variable names that the harness shim should retain in trace output.
env dict[str, str] no Environment-variable mapping supplied to the related build, scenario, or command step.
secrets dict[str, str] no Secret environment variables that the harness should expose to the scenario while keeping them logically separate from ordinary environment variables.
workspace_files list[WorkspaceFile] no Files that the harness should create directly in the scenario workspace before execution begins.
git_repositories list[GitRepositoryFixture] no Disposable Git repositories that the harness should create in the scenario workspace before execution begins.
tool_behaviors dict[str, list[ToolBehavior]] no Scripted intercepted-tool behaviors keyed by tool name in the related harness scenario or runtime state.
jobs list[JobScenario] no Jobs that the harness should execute for the related custom scenario.
workflow WorkflowScenario no Nested workflow block for an act harness scenario, or the workflow name recorded in provenance.

HarnessSequenceEntryJson

One sequence-run entry returned by the harness CLI.

  • category: runtime
  • ownership: runtime-derived
  • file contract: (inner type)
Field Type Required Description
scenario str yes Scenario name associated with the related harness sequence result entry.
workspace str yes Filesystem path of the harness workspace directory for the related run.
inspectable_paths HarnessInspectablePaths yes Paths that a harness caller can inspect after the run to understand rewritten workflows, summaries, and persisted state.
selected_job_ids list[str] no Harness job ids selected for execution in the reported run.
failed_job_ids list[str] no Harness job ids that finished with a failure outcome in the reported run.
blocked_job_ids list[str] no Harness job ids that were not run because an upstream dependency failed or was blocked.
job_statuses dict[str, HarnessJobStatus] no Final per-job status map emitted by the harness for the reported workflow or sequence run.

HarnessSequenceRunResultJson

Machine-readable JSON payload for one harness sequence run.

Field Type Required Description
sequence list[HarnessSequenceEntryJson] no Ordered per-scenario results retained for one multi-scenario harness sequence run.
final_workspace str yes Filesystem path of the final harness workspace retained after a multi-scenario sequence run.

HarnessShimState

Persisted subprocess-facing harness shim state.

  • category: runtime
  • ownership: runtime-derived
  • schema file: harness-shim-state.schema.json
  • audience: internal
  • stability: stable
  • file contract: (inner type)
Field Type Required Description
workspace_root str yes Filesystem path of the harness workspace root used by the persisted shim state.
trace_file str yes Filesystem path where the harness shim appends structured command trace entries.
env_capture list[str] no Environment variable names that the harness shim should retain in trace output.
tool_behaviors dict[str, list[ToolBehavior]] no Scripted intercepted-tool behaviors keyed by tool name in the related harness scenario or runtime state.
counts dict[str, int] no Per-tool or per-key invocation counts retained in harness runtime state.
gh_tag_objects dict[str, HarnessBuiltinGhTagObject] no Synthetic GitHub annotated-tag payloads persisted in harness shim state for later ref mutation handling.
gh_releases dict[str, HarnessBuiltinGhRelease] no Synthetic GitHub Releases keyed by exact tag.
gh_next_release_id int no Next synthetic GitHub Release identifier allocated by the stateful shim.
gh_next_asset_id int no Next synthetic GitHub Release asset identifier allocated by the stateful shim.

InvocationMatch

A matcher for a single intercepted tool invocation.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
argv list[str] no Exact argv list that the harness should match or that it recorded for the related command invocation.
argv_prefix list[str] no Command-line prefix that the intercepted argv list must start with before the harness behavior matches.
argv_contains list[str] no Command-line fragments that must appear somewhere in the intercepted argv list before the harness behavior matches.
cwd str no Working directory that the harness should use or that it observed for the related command invocation.
env_contains dict[str, str] no Subset of required environment entries that a harness tool matcher must observe.

JobScenario

A job in the harness scenario.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
id str yes Stable identifier for the related harness job, step, or scenario element.
needs list[str] no Job ids that must complete successfully before the related harness job is allowed to run.
env dict[str, str] no Environment-variable mapping supplied to the related build, scenario, or command step.
steps list[StepScenario] yes Ordered shell steps that the harness should run for the related custom job.

StepScenario

A single shell step in a harness job.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
id str yes Stable identifier for the related harness job, step, or scenario element.
run str yes Shell command body that the harness should execute for the related step.
cwd str no Working directory that the harness should use or that it observed for the related command invocation.
env dict[str, str] no Environment-variable mapping supplied to the related build, scenario, or command step.
shell str no Shell executable name or mode that the harness should use for the related step.

SvnRepositoryFixture

Initial ASF SVN state to create inside one harness act workspace.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
initial_state SvnInitialState no Named SVN fixture preset that describes what ASF dist state the harness should create before the run begins.
version str no Release version string without a leading v prefix.
rc_number int no Numeric RC sequence selected for the related version.
other_version str no Additional release version that the SVN harness fixture should materialize for preset scenarios that require another version line.
dev_dist_entries list[str] no Initial SVN entries that the harness should create under the simulated ASF dist/dev tree.
release_dist_entries list[str] no Initial SVN entries that the harness should create under the simulated ASF dist/release tree.
repository_files list[WorkspaceFile] no Files that the harness should create inside the simulated SVN repository fixture before execution begins.

ToolBehavior

A scripted behavior for an intercepted tool invocation.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
match InvocationMatch no Tool-invocation matcher that decides when the related scripted harness behavior should be applied.
result ToolBehaviorResult no Scripted harness tool result that should be returned when the matching invocation is observed.
times int no Maximum number of times that the harness should apply the scripted tool behavior before it stops matching.

ToolBehaviorResult

The mocked result of an intercepted tool invocation.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
exit_code int no Process exit code that the harness recorded or should synthesize for the related tool invocation.
stdout str no Captured stdout that the harness recorded or should synthesize for the related tool invocation.
stderr str no Captured stderr that the harness recorded or should synthesize for the related tool invocation.
summary str no Human-readable short summary for the related result or mocked tool behavior.
append_stdout_to_summary bool no Whether the harness should append mocked stdout to the rendered step or job summary output.
delegate_to_real_tool bool no Whether the harness should fall through to the real external tool instead of returning the mocked result directly.
writes list[FileWriteAction] no Files that the mocked tool behavior should write when the invocation matches.

WorkflowRepositoryBranchFixture

A branch that should exist in the workflow repository checkout before execution.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
name str yes Stable name for the related object, branch, tag, release, or harness step.
start_point str no Commit, ref, or symbolic start point that the harness should use when creating the related branch or tag.

WorkflowRepositoryFixture

Git refs that should be created in the workflow repository checkout before execution.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
branches list[WorkflowRepositoryBranchFixture] no Git branches that the harness should create in the workflow repository fixture before execution begins.
tags list[WorkflowRepositoryTagFixture] no Git tags that the harness should create in the workflow repository fixture before execution begins.

WorkflowRepositoryTagFixture

A tag that should exist in the workflow repository checkout before execution.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
name str yes Stable name for the related object, branch, tag, release, or harness step.
target str no Target commit, ref, or identifier that the related fixture or release record should point at.
annotated bool no Whether the related Git tag fixture should be created as an annotated tag instead of a lightweight tag.
message str no Human-readable message body associated with the related verification failure, harness tag object, or fixture definition.

WorkflowScenario

A real workflow-YAML invocation executed by the act backend.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
path str yes Filesystem path, relative artifact path, or retained evidence path associated with the related record.
event Literal[‘workflow_dispatch’] no Workflow event name that the harness should simulate for the related workflow scenario.
inputs dict[str, str] no Workflow-dispatch inputs that the harness should pass to the selected workflow invocation.
harness_config str yes Path to the harness configuration file that the act workflow scenario should load.
release_config dict[str, object] no Optional complete release configuration used only inside the disposable workflow workspace.
real_cli_commands list[str] no External CLI command names that the act harness workflow may run directly instead of through shim wrappers.
repository_fixture WorkflowRepositoryFixture no Workflow-repository ref fixture that the harness should materialize before running the selected workflow.
gpg_fixture GpgFixtureMode no GPG fixture mode that the harness should prepare for the related workflow scenario.
svn_fixture SvnRepositoryFixture no SVN fixture preset that the act workflow scenario should create before execution begins.

WorkspaceFile

A file that should exist in the scenario workspace before job execution starts.

  • category: authored
  • ownership: consumer-owned
  • file contract: (inner type)
Field Type Required Description
path str yes Filesystem path, relative artifact path, or retained evidence path associated with the related record.
content str yes Literal file content that the harness should write or that the mocked tool should emit.
executable bool no Whether the written file should have the executable bit set in the harness workspace.