Durable repository creation
This portable contract describes its linked source snapshot. For current deployment instructions, use current installation, authentication and native Cloudflare guides. Historical receipts do not verify later builds.
Create a repository in your own Forgejo namespace through Golf, then inspect the same request after a disconnect or restart. Golf records the intent before sending the native create request. Reusing its key never sends that write again, even when Golf cannot determine the outcome.
This is a bounded creation workflow. It does not implement organization creation, general background jobs, imports, deployments or protected Git publication. The API reference describes the generated contract; the product's creation contract records implementation evidence and limits at commit 9d0ce66.
Create from the browser
After sign-in, select New repository, enter its name and optional description, and choose visibility. Private is the safe default; creating a public repository requires an explicit choice. A PAT needs write:user and write:repository; the user's native permissions remain authoritative. Golf does not substitute an administrator credential.
Selecting Create repository generates one cryptographically random UUID and freezes the submitted inputs. Golf binds that key to the exact name, description and visibility within your immutable account and configured forge. An unchanged request can be inspected or replayed with that key. Changing any input, including whitespace, requires a separate explicit intent.
| Recorded outcome | What it means | What to do |
|---|---|---|
OUTCOME_UNKNOWN | Golf reserved the dispatch. The write may still be running, may never have reached Forgejo, or may have completed without a usable acknowledgment. | Use Check status. Do not create another intent just because a request timed out. |
SUCCEEDED | Golf committed evidence of a native success with the expected owner/name/visibility and exact repository ID. | Open the repository if current access can be confirmed. Historical success alone does not grant access. |
REJECTED | Golf recorded a native rejection, with a bounded status category. | Review the cause. Start a new request deliberately unlocks editing and creates a new key on submission. |
Retry same request is available only while the original submitted payload remains in memory. It reuses that key and frozen payload; the server reads the existing operation instead of issuing another provider POST. A known rejection remains rejected when replayed, even if a later credential has broader scopes.
Resume after closing or reloading
An unresolved operation exposes Resume repository creation when the dialog is reopened or the same tab reloads. This resumes status inspection only: it does not automatically submit another create request or reconstruct the description.
The tab's session storage keeps only the pending key, name and visibility, scoped to the exact browser origin and current native user ID. It stores no description, token or authentication cookie. Sign-out, expiry or account changes clear this state and private queries. Closing the tab may discard it; this is not a durable client-side operation directory. Keep an operation key separately when a script or longer investigation needs it. A key is correlation metadata, not authentication.
When a successful result includes freshly authorized repository metadata, the dialog closes, the list refreshes and the pending marker is removed. If Golf cannot confirm access, it keeps the recorded success visible without presenting a repository object. Deletion, rename, lost permission/scope or replacement at the same name can produce that result. A replacement with a different native ID is never adopted as the original operation's repository. A transient provider outage remains a visible error.
Inspect from the CLI
The read-only CLI can inspect an existing key:
# Supply the scoped token through stdin, not as a command argument.
./bin/golf --token-stdin repo creation 12345678-1234-4234-8234-123456789abc
Replace the example with the canonical lowercase UUID v4 returned for your operation. read:user is sufficient to inspect your record; current repository metadata additionally depends on repository scope and native access. The command signs into Golf, reads the record and logs out before emitting its golf.cli.v1 JSON response. It cannot create, redispatch or resolve an unknown operation.
A successful inspection can return OUTCOME_UNKNOWN or REJECTED with exit 0. That means the lookup succeeded, not that a repository was created. Check data.creation.state and the optional data.repository separately. Missing and foreign keys receive the same not_found response; revoked or expired callers cannot read the record.
Use a stable API key
Generated clients call RepositoryService.CreateRepository with name, description, explicit private and idempotencyKey. Save one UUID v4 per deliberate intent and reuse the exact payload with it. All application RPCs still require a valid session and exact configured Origin.
Keyed requests can return HTTP 200 with any recorded state. Inspect creation.state rather than equating transport success with creation success. GetRepositoryCreation reads an existing key without submitting a write. Reusing a key with different inputs returns failed_precondition; invalid keys return invalid_argument.
Omitting the key preserves older callers' RPC error behavior, but Golf still journals a generated intent before dispatch. A successful response includes that generated key. Repeating an unkeyed call creates a new intent and cannot provide retry deduplication. Different keys likewise authorize distinct intents; native name uniqueness does not establish operation-level exactly-once execution.
Durability and limits
Operation state and its initial/terminal events commit together in PostgreSQL. These events are separate from Account activity, which remains session history. The description is sent to Forgejo but not retained as operation text. The journal has no automatic expiry, public event-list API or supported manual-resolution operation. Database-owner privileges can alter ordinary SQL history guards; this is not cryptographically immutable evidence.
The schema 202610020004 coordinated Docker recovery preserves creation records and events while invalidating restored Golf sessions and pending PKCE. Restore does not dispatch operations, automatically adopt an existing repository or turn an unknown result into success. Authoritative reconciliation of post-backup changes, native revocations/deletions, outbound work and ambiguous in-flight effects is still required before reopening traffic.
A local session revocation, client cancellation or timeout cannot undo a native write already accepted. This endpoint's one-dispatch rule does not fence a paused provider request or provide a general exactly-once broker. Outbox/jobs, organization and tenant authorization, protected publication, retention/export and automatic unknown-outcome resolution remain open.
Qualified behavior
The current development increment passes real PostgreSQL race tests, 72 browser fixture checks plus targeted payload-mismatch validation, native Forgejo creation/rejection and restart checks, CLI privacy/cleanup, and production-browser reload, keyboard, charcoal/light mobile and revoked-session cleanup. The browser reserves its intent before React updates the form, so two immediate submissions retain one key. The browser test drops a real successful response after Golf records it; a reload inspects that recorded result without another submission.
A separate controlled native fault test discards Forgejo's actual HTTP 201 acknowledgment before Golf receives it. The repository exists, but Golf retains OUTCOME_UNKNOWN; repeated requests and a real Golf restart leave the observed native POST count at exactly one, without adoption. Fresh schema 202610020004 recovery also preserves operation/event rows and authenticated replay behavior. These are bounded fixture proofs, not load, capacity, general recovery or protected-write qualification. See implementation status.