GOLF / GOLF FOR DEVELOPERS

Your code. Your next move.

A practical source-to-preview workflow.

THE PRODUCT

From source to software.

Golf connects Git, collaboration, executable evidence, optional proposals and protected previews.

01

Source

Repositories, history, issues, PRs and human review.

02

Evidence

Approved exact-source tests, reports and proposals.

03

Delivery

Protected static and bounded Worker app previews.

THE DAILY LOOP

Code. Check. Review. Preview.

Follow one exact change through the workspace.

01

01 / Source

Select the repository, branch and exact commit.

02

02 / Change

Open an issue or same-repository PR and request review.

03

03 / Check

Run an authorized profile and inspect the terminal report.

04

04 / Preview

Publish an allowed protected preview and inspect the result.

DEPLOYMENT / DOCKER

Docker: the portable Golf stack.

Run a complete developer core on your machine or owned Docker infrastructure.

01

What runs

Golf React/Go, Forgejo and independent PostgreSQL databases/roles. Private configuration and persistent volumes survive ordinary restarts.

02

How to start

Initialize private environment files, start Compose, check /readyz, then enroll a mapped Golf account. Optional Docker workers, agents and object storage require their own setup.

03

What you own

Image/version choices, HTTPS beyond loopback, secrets, data volumes and coordinated recovery. No Cloudflare or AI account is needed for core work.

DEPLOYMENT / DOCKER

Docker: what runs, what persists.

The portable core uses Forgejo and PostgreSQL. Execution workers are allocated separately.

Editable architecture diagram · Open full size ↗

DEPLOYMENT / KUBERNETES

Kubernetes: deploy Golf deliberately.

Golf’s Helm chart packages the portable core and makes its operating boundaries explicit.

01

What the chart supplies

Golf replicas, one Forgejo writer, optional PostgreSQL, resources/probes, retained claims, non-root isolation and default-deny policies.

02

How it is hardened

Upgrade identity/endpoint fences, API hostname spread and multi-replica disruption budget, graceful drain, private database CA mounts and explicit DNS/egress peers.

03

What you supply

Built image, existing credential/certificate Secrets, enforcing CNI, storage, ingress/TLS/DNS and a tested recovery procedure. Runners and agent services remain separate.

DEPLOYMENT / KUBERNETES

Kubernetes: placement and ownership.

API replicas share one forge writer and retained storage. More replicas alone do not establish HA.

Editable architecture diagram · Open full size ↗

DEPLOYMENT / NATIVE CLOUDFLARE

Cloudflare: a native hosted control plane.

Artifacts, D1 and Workers replace origin-backed forge infrastructure on this track.

01

What runs

Shared UI/Connect services in Workers; Artifacts canonical Git; D1 collaboration/policy; SQLite Durable Objects coordinating reads and execution.

02

How the workflow grows

Queues, Workflows and Containers produce evidence. Private R2, managed registry and protected Worker apps retain outputs. Optional AI, browser snapshots, email and operations add focused consumers.

03

How to deploy

Alchemy or the native cf recipe provisions owned resources under the selected account, Access identity, domains, images and permissions. Verify actual schema, grants, readback and cleanup.

DEPLOYMENT / CLOUDFLARE

Cloudflare: where each part lives.

Workers own the application, Artifacts owns Git, and D1 owns collaboration state.

Editable architecture diagram · Open full size ↗

NATIVE ARCHITECTURE

A platform built from managed primitives.

Each service has a specific role. Golf retains current authorization.

Editable architecture diagram · Open full size ↗

SOURCE + COLLABORATION

Canonical Git. Explicit authority.

The control plane is native to Cloudflare.

01

Workers

Shared React UI, generated Connect APIs, Git brokerage and trusted service entrypoints.

02

Artifacts

Canonical Git objects and refs, source/history and independent proposal forks.

03

D1

Accounts, repository grants, collaboration, policy, operation receipts and job records.

04

Durable Objects

Workspace and RepositoryReads coordination; PRTestTask and PRAgentTask execution authority.

EXECUTABLE EVIDENCE

Durable admission. Bounded compute.

Run a selected exact-source profile and retain what actually happened.

01

Queues + dead-letter queue

Buffer evidence admission; optional DLQ retains exhausted messages for deliberate recovery.

02

Workflows

Retain staged orchestration and outcomes; never grant repository authority.

03

Containers

Approved images execute checks and proposals with bounded source and network access.

04

Sandbox SDK file helpers

File staging inside raw Containers. A separate general Sandbox runtime is not implied.

EXECUTABLE EVIDENCE / THE FLOW

Follow one exact-source check.

From authorized admission to retained private evidence.

Editable architecture diagram · Open full size ↗

STORAGE + DISTRIBUTION

Keep the source. Keep the proof.

Use different storage for different responsibilities.

01

Artifacts

Git history and proposal forks, with current reader/writer checks.

02

Private R2

Reports, agent context, preview bundles, release assets and discussion attachments.

03

Managed image registry

Approved execution images and CI publication on registry.cloudflare.com; Golf retains digest receipts.

04

Secrets Store

Broker authority, signing material and encryption keys; never browser-held provider secrets.

STORAGE + DISTRIBUTION / THE FLOW

Source, state and outputs.

Give each kind of data the right home.

Editable architecture diagram · Open full size ↗

WORKERS AI + AI GATEWAY

Advice and proposals have different jobs.

Optional inference serves a specific workflow.

01

Clef advice

Metadata-only PR reasoning through Workers AI. Advisory evidence; no approval or merge authority.

02

GLM 5.3 Flash proposals

Maintained harness in an independent Artifacts fork. Approved file changes, tests and private reports.

03

AI Gateway

Authenticated inference; logs and cache disabled. Configured 60/min and $5/day limits.

WORKERS AI + AI GATEWAY / THE FLOW

Two AI paths. Explicit authority.

Clef advice and separately tested proposals serve different jobs.

Editable architecture diagram · Open full size ↗

PROTECTED DELIVERY

Review a running change.

Temporary, source-bound previews keep production separate.

01

Preview Worker + R2

Broker the exact static bundle with current reader checks and expiry.

02

Workers for Platforms

Dispatch approved modules with private per-preview D1/R2 and signing material.

03

Outbound Worker

Enforce the managed app egress policy instead of handing apps unrestricted Internet access.

04

Browser Run

Optional script-free static HTML snapshots. Full interactive application QA remains open.

PROTECTED DELIVERY / THE FLOW

The preview has its own boundary.

Protect readers and isolate the application’s data and network access.

Editable architecture diagram · Open full size ↗

IDENTITY + DOMAINS + POLICY

Identity is the start of permission.

Access, Golf authority and deployment policy work together.

01

Access / Zero Trust

Separate human OTP and machine service admission; Golf requires an enrolled account and current grants.

02

DNS, custom domains + TLS

Owned-zone control/preview hostnames and email sender records. Protection covers approved endpoints.

03

Secrets + environment policy

Encrypt repository values; approve exact-commit PR workflow release. Restrict preview branch, lifetime and concurrency.

04

Workers rate limiting

Approximate anonymous read/clone throttling by network and location. Errors fail open; not a global quota.

IDENTITY + DOMAINS + POLICY / THE FLOW

From identity to permission.

Release secrets only to the approved exact-commit workflow.

Editable architecture diagram · Open full size ↗

EMAIL + WEBHOOKS

Keep people connected to the work.

Real messages retain consent, current access and delivery observations.

01

Email Service

Own-address subscriptions and consent; sender subdomain and DNS onboarding. Retained provider acceptance is recorded.

02

Signed webhooks

Encrypted subscriptions, approved origins and stable event identity. A retained Slack test delivery was accepted.

03

D1 outboxes

Maintenance and bounded retries carry notification delivery. These consumers do not use the evidence queue.

EMAIL + WEBHOOKS / THE FLOW

Keep the operating loop visible.

02

Choose your deployment

Docker Compose or Golf’s Helm chart for portable hosting. Use the native Alchemy recipe in your own Cloudflare account.

03

Evaluate real work

Enroll a user and grant repository access on your installation. Check an exact commit and inspect its report. docs.gitgolf.app

gitgolf.app/try ↗