Product · How it works

Coordination around real Git.

Every Switchyard workflow ultimately produces or evaluates ordinary Git state hosted in Cloudflare Artifacts.

The ordinary Git path

developer
  └─ git clone / fetch / push
          └─ Cloudflare Artifacts
                 └─ real objects, commits, branches and refs

Switchyard does not proxy those concepts into a replacement source-control model. It reads and mutates the same remote Git repository.

The Switchyard path

Step	Coordination state	Git effect
Work	An intent/task is recorded in Switchyard/Trestle.	None required.
Attempt	An isolated candidate execution is tracked.	Isolated branch/ref state exists in the Artifacts repository.
Human or Agent edit	Execution/draft/provenance is recorded.	Ordinary commits are produced on the candidate branch when committed.
Pull Request + review	Checks, findings, approvals and risk are tracked.	Preview uses the real branch and target Git trees.
Integration Queue	Freshness, checks, policy and ordering are enforced.	A real Git operation moves canonical in Artifacts.

Why the Integration Queue matters

Multiple Attempts can be valid independently and still become stale relative to one another. The queue serializes canonical movement, re-previews work against the latest target and lets Git's own stale-write behavior protect the ref underneath Switchyard's higher-level policy.

Durable workflows

JavaScript workflows call durable Switchyard operations such as agent execution, checks, review and integration. The orchestration state belongs in Trestle; the repository effects belong in Git/Artifacts. On replay, completed external effects are not blindly repeated.

External Git activity

If somebody pushes from a terminal or CI system, Artifacts changes immediately because it is the remote Git server. Switchyard then observes that Git movement through events and reconciliation and updates its durable coordination/provenance view.

Useful mental modelArtifacts answers “what is in Git?” Trestle answers “what is Switchyard doing about it?”

A concrete change, end to end

Moment	Switchyard state	Git/Artifacts state
1. Someone opens Work	Work records intent, owner and discussion.	No Git change is required yet.
2. Implementation starts	An Attempt records the candidate and actor/executions.	A real isolated branch exists in the Artifacts repository.
3. Files change	Draft/execution provenance is recorded as appropriate.	When committed, ordinary Git commits appear on the Attempt branch.
4. PR opens	Checks, findings and review state become visible.	The PR still references normal source/base Git refs.
5. Queue evaluates	Freshness, policy, conflict state and risk determine whether it may integrate.	Preview reads the actual current base tree.
6. Integration succeeds	Queue/provenance records the decision and outcome.	A real non-force Git operation moves canonical in Artifacts.

What happens when somebody bypasses the UI?

Nothing breaks conceptually. If a developer pushes directly from a terminal, Cloudflare Artifacts changes immediately because it is the Git server. Switchyard observes that ref movement through the event/reconciliation paths and updates its coordination view. This is an important design property: the browser UI is a collaboration surface, not a mandatory proprietary transport layer.

Simple caseOne human with zero Agents can still clone, branch, push, browse history, create Work, open a Pull Request and integrate under repository policy. Agent-native concepts remain additive.

Two interface paths

Git transports repository state. The browser, sy CLI and HTTP API operate on the collaboration layer.

Git client → Cloudflare Artifacts → objects and refs
Browser / sy / HTTP API → Switchyard control plane
                       → Trestle coordination and workers