This is an unreleased pilot. Use SDK and plugin builds containing the cloud implementation.
The direct flow is locally tested. A live customer replay has not yet been verified.
Set up once
Ask your coding agent to run bitfab:setup cloud.
It inspects your existing GitHub Actions and replay registry.
It adapts the runtime, dependency installation, build steps, services, and working directory.
The setup installs three files.
.bitfab/cloud.json defines one pipeline and its fixed replay command..bitfab/cloudReplay.py handles snapshots, dispatch, recovery, and runner execution..github/workflows/bitfab-replay.yml builds the environment and runs replay.
No Bitfab GitHub App connection or server-side cloud target is required.
You need git, Python 3.10+, and an authenticated gh locally.
The initial client supports macOS and Linux with a github.com origin.
Normal Git push authentication must also work.
Your GitHub identity needs permission to push branches and dispatch Actions.
Creating or changing workflow files may require additional workflow permissions.
Create the requested secrets in GitHub’s repository or Environment settings.
Include BITFAB_API_KEY for the intended Bitfab organization.
Application secrets such as OPENAI_API_KEY depend on your code.
Use a GitHub Environment with required reviewers when appropriate.
Never put secret values in workflow inputs, configuration files, or chat.
An optional BITFAB_SERVICE_URL variable can select a non-default service.
Omit that binding when using the SDK default.
Review push-triggered CI and deployment integrations.
Pushing bitfab-replay/** branches may trigger them.
Exclude those branches where needed before enabling replay.
Setup records this review through pushTriggersReviewed.
Commit the setup files and land the workflow on your default branch.
GitHub requires this before a workflow can be dispatched on another branch.
See GitHub’s manual workflow requirements.
Setup does not merge code or configure secrets automatically.
Run replay
Review the source snapshot first.
Tracked files use their current working contents.
New files, including staged additions, require explicit inclusion.
Paths passed to --cloud-include are repository-relative.
The command creates an isolated snapshot commit.
It pushes a unique bitfab-replay/EXECUTION_UUID branch.
It dispatches your workflow on that branch and waits for completion.
It retrieves the Bitfab test-run ID from a small Actions artifact.
It then deletes the temporary branch using an exact-commit check.
Your HEAD, staging area, and working files remain unchanged.
There is no local commit to undo.
The snapshot commit remains in Git’s object storage until normal garbage collection.
Deleting a remote branch does not erase commit history or Actions retention.
The remote replay reads traces and writes results through normal Bitfab APIs.
This is not offline replay.
Python and Ruby use the same flags through their SDK command.
Go uses the project’s registry executable.
Go applications must call RunCloudReplayCLI before initializing the registry.
The other SDKs bypass application imports for cloud commands.
Status, cancellation, and recovery
Use --cloud-detach to return after dispatch.
Execution records live in <worktree-git-directory>/bitfab-cloud/.
Recovery commands must run from the same worktree.
The execution UUID is printed to stderr before the branch is pushed.
Closing the terminal after dispatch does not cancel the remote run.
A detached job needs a later watch, status, or cleanup command to remove its branch.
Cancellation requests are asynchronous.
Status includes the Actions URL and infrastructure conclusion.
Successful jobs also expose testRunId.
Infrastructure success does not mean every assertion or grader passed.
The result artifact contains identity only and is retained for seven days.
Cleanup remains possible after artifact expiry.
If a dispatch response is lost, inspect status using the printed UUID.
Resubmitting identical arguments with --cloud-request-id EXECUTION_UUID recovers the original execution.
It never dispatches that request twice.
It does not capture subsequent source edits under the same ID.
Use a new execution for new code.
Do not use GitHub’s rerun button. Runner retries are rejected.
Cleanup refuses a running or uncertain execution.
If dispatch fails or times out without a discoverable run, the temporary branch stays in place.
Retry --cloud-status EXECUTION_UUID to look for a run.
A missing run does not prove that GitHub rejected the request.
This pilot has no automatic cleanup or force-cleanup command for uncertain executions.
Inspect GitHub Actions and confirm that no job needs the snapshot before manually deleting its temporary branch.
A request interrupted before dispatch remains prepared.
Clean up that request before submitting a new UUID.
If the remote branch has moved, cleanup refuses to delete it.
Inspect the branch manually rather than force-deleting it.
Configuration reference
Example for a Node project whose registry is in scripts/replay.ts.
workingDirectory and registry are repository-relative.
Set registry to null for Go.
The command runs in workingDirectory.
Registry paths inside the command are relative to that directory.
Do not include the pipeline or request flags in the fixed command.
The runner appends validated trace IDs, concurrency, and --no-code-change.
Setup uses the bundled helper’s init --config FILE command.
The setup specification includes the configuration above.
It also includes setupSteps as GitHub Actions step objects.
Optional fields are secrets, variables, environment, services, and runsOn.
Secrets and variables contain names only.
The initializer refuses to overwrite existing files.
It emits JSON-formatted YAML, accepted by GitHub Actions.
The default job has read-only repository permissions.
Checkout does not persist credentials.
Application secrets are scoped to the replay step.
Install-time credentials require explicit references in the relevant setup step.
The dispatch adapter uses GitHub’s versioned workflow dispatch API.
If the response is lost, it identifies the run by branch, snapshot SHA, and execution title.
Limits and safety
The pilot accepts 1–100 explicit trace UUIDs.
--max-concurrency accepts 1–32.
Other replay options are rejected.
Configure defaults in your registry.
One pipeline is configured per repository.
Submodules and gitlinks are not supported.
Ignored files and credential-like paths are rejected.
Common .env.example, .env.sample, and .env.template files are allowed.
Filename checks are not secret scanning.
Review the complete snapshot before pushing.
Only trusted code should run with your Actions secrets.
A writable workflow and its dependencies can access those secrets.
Replay mocking remains responsible for preventing unsafe side effects.
A CI runner is not a substitute for replay-safe application code.
Private services need reachable test infrastructure or an appropriate runner.
The generated job has a 35-minute timeout.
The replay subprocess has a 25-minute timeout and a 16 MiB stdout limit.
Local watch stops after 40 minutes without cancelling the remote job.
Resume it using the execution UUID.
The Bitfab monorepo currently contains orphan gitlinks and tracked credential-like files.
A full-monorepo snapshot is intentionally blocked.
Use an approved, suitable checkout for the live pilot.
The earlier mocked Actions smoke run does not verify this direct replay flow.
