main
ply4 git calls501 ms60 KiB2 cachedprotocol v2
a262b639

pin ply 1991256 (both-in-one-push accepts either surviving ref)

ply Worker — https://ply.ivar.workers.dev

A Cloudflare Worker that exposes ply as an HTTP API against any smart-HTTP git host. The git client is github:ivarvong/ply#af5cac0372df6caf774d108cbf9229b04af45eb6 (an exact commit of ply main; an operator moves the pin with npm run cd -- bump). The /v1 git API has no storage. GET /view is a public repository viewer, rate-limited by client through a SQLite Durable Object. One Artifacts namespace, public-v0, is served read-only with no token (/r/<repo>, see Public namespace). Feature flags are one R2 object and a service binding (Feature flags). GET / prints the usage text.

Auth

  • Gate: Authorization: Bearer <PLY_TOKEN> on /v1. GET /, GET /view, GET /view.css, GET /r/<repo>, and the /v1 reads of the public namespace are public. The token is a Worker secret (cf workers secrets update PLY_TOKEN --worker ply --type secret_text) and is compared in constant time (SHA-256 of both sides, then crypto.subtle.timingSafeEqual). A missing or wrong token returns 401 {code: "unauthorized"}.
  • Git credential (optional; public repos need none):
    • Git-Authorization: <value> is sent upstream verbatim as Authorization.
    • Git-Token: <token> is mapped by host: github.com → Basic x-access-token:<token>, gitlab.* → Basic oauth2:<token>, anything else (Cloudflare Artifacts included) → Bearer <token>. Artifacts accepts Bearer and Basic; both were checked in the smoke run.
    • Sending both headers is a 400.
    • Neither credential appears in a response, trace, error message or log line. ply never records them, and the Worker scrubs every outgoing string as a second layer (test/worker.test.js greps all of these, including a hostile upstream that echoes the header back).
  • Remote rules: remote must be https:, on the default port, with no userinfo, query, or fragment. The host is canonicalised (lowercase, no trailing dot — github.com. is rejected rather than stripped). IP literals are refused in every encoding the URL parser accepts (dotted, zero-padded, octal, hex, decimal 2130706433, IPv6, IPv4-mapped, IPv4-compatible). So are single-label hosts, localhost/.local/.internal/.lan/.home.arpa/… names, and wildcard-DNS names (nip.io, sslip.io, localtest.me, and the same shape of zone). A path segment of . or .., or an encoded slash, backslash, or dot (%2f, %5c, %2e), is rejected before normalisation. Redirects follow git's http.followRedirects=initial: ply follows a 3xx only on the first GET info/refs (at most three hops, and only when the Location keeps the /info/refs?service=… suffix), and every later request, POSTs included, goes to the rewritten base. ply's allowUrl hook (remoteAllowUrl, src/remote.ts) vets each new base with the same check, on the same origin. A 3xx on a POST, a loop past three hops, or a Location git would not rebase to is a 400 with code http naming the target (git cannot use such a remote either). The Worker's fetch wrapper (createGuardedFetch) re-checks every request and never follows a 3xx itself; a 3xx whose Location is on another origin or fails the check is a 400 bad_request before ply sees it, so a credential never leaves the origin (test/worker.test.js, "redirects"). ALLOW_REMOTE_ORIGINS (comma-separated origins) exempts those origins from the public-host rules (http, an IP, a non-default port). Only the tests use it.

Endpoints

MethodPathInputOutput
GET/v1/refsremote, prefix?{refs: {name: oid}, head, peeled: {tag: commit}}. An empty repository adds {empty:true, unborn:"refs/heads/main"} and leaves head null
GET/v1/discoverremoteprotocol v2 capabilities (agent, fetch, filter, caps, …)
GET/v1/readremote, ref?, paththe blob, streamed. Headers: content-length, x-ply-ref, x-ply-commit, x-ply-blob, x-ply-mode, x-ply-size. A directory is 400 bad_request (list it with GET /v1/tree), not 404
GET/v1/treeremote, ref?, path?{ref, commit, tree, entries: [{name, mode, oid, type}]} (modes as git ls-tree prints them)
GET/v1/commitremote, ref?born: {ref, oid, tree, parents, author, committer, message, signed}. author/committer are {name, email, time, epoch, tz} (time ISO-8601 UTC, epoch the raw seconds, tz as written, e.g. +0530). message is the raw body. signed means a gpgsig header is present (not verified). Fetches the commit only (tree:0, deepen 1; blob:none when the server refuses that). Empty repository (unborn HEAD, or that same branch by name): {empty:true, ref:"refs/heads/main", oid:null, tree:null, parents:[], author:null, committer:null, message:null, signed:false}. A different missing ref stays 404. A born response does not grow an empty field
POST/v1/edit{remote, ref?, base?, author, committer?, message, head?, changes?} or the one-file form {path, find?, replace?, content?, delete?, to?, mode?}{outcome, ref, oid, oldOid, noop, tree, newCommit, oldCommit}. newCommit/oldCommit alias oid/oldOid. A root commit and any newly created ref have oldOid: null
POST/v1/branch{remote, ref, from?}201 {outcome:"created", ref, oid, oldOid:null}. from is a branch or a 40-hex commit. Omit from only when HEAD is born
DELETE/v1/branch{remote, ref, oid?}{outcome:"deleted", ref, deleted}. CAS on oid (default: the oid ls-refs shows now)
POST/v1/tag{remote, name, target, annotated?, message?, tagger?}201 {outcome:"tag", ref, oid, commit, annotated}. Lightweight unless annotated, message, or tagger is set. target is a branch or a commit id
DELETE/v1/tag{remote, name, oid?}same compare-and-swap as DELETE /v1/branch
POST/v1/merge{remote, ref?, from, author?, committer?, message?, fastForwardOnly?, noFastForward?}{outcome, ref, oid, oldOid, noop, …} where outcome is merge, fast_forward, or up_to_date. from is a branch or a 40-hex commit. author and committer are separate stamps, each with its own time and tz
POST/v1/rebase{remote, ref, onto?, committer, author?, squash?, message?}{outcome, ref, oid, oldOid, …} where outcome is rebase, squash, fast_forward, or up_to_date. onto is a branch or a 40-hex commit. author.time and committer.time are independent
POST/v1/cherry-pick, /v1/revert{remote, ref?, commit, committer, message?, allowEmpty?}{outcome, ref, oid, oldOid, noop, tree?}. A patch already applied, and only when both sides added and deleted the same paths, is {outcome:"empty", noop:true, oid:<tip>}. allowEmpty:true writes that empty commit. If the target also has its own adds or deletes, the response is 409 merge_conflict (allowEmpty does not override it)
GET/v1/flagsthe cached flag ruleset {revision, cache, environment, flags}. Writes are not this route
POST/v1/flags/eval{unit, attributes?, keys?}{revision, cache, flags:[{key, variant, reason, bucket}]}. Per-unit; the response is no-store

Flag writes are not HTTP (PUT/POST/PATCH/DELETE /v1/flags are 405). Operators call scripts/flags, which talks to the ply-flag-operator Worker. That Worker checks FLAG_OPERATOR_TOKEN and calls FlagControl (setRollout, setTargeting, getConfig) over a service binding. The design, the basis-point allocation, and the staleness bound are in Feature flags.

  • ref defaults to the remote's HEAD branch. On an empty repository HEAD is an unborn symref (refs/heads/main on Artifacts and on git init -b main). GET /v1/commit reports that as empty: true and names the symref. POST /v1/edit with no ref creates the root commit on that branch. Merge, rebase, cherry-pick, revert, and branch-from cannot use an unborn HEAD: the response is 400 naming the missing field (ref, onto, or from). Naming that unborn ref explicitly is 404 ref refs/heads/main is unborn; create a commit before ….
  • On reads, short names resolve the way git rev-parse does: tags win over branches, and a 40-hex commit oid is also accepted. An abbreviated oid (7–39 hex) resolves only when it matches one advertised ref (a branch tip, a tag tip, or a peeled tag commit); otherwise the response is 400 bad_request asking for the full oid. On writes, short names mean refs/heads/<name>. A 40-hex string is a commit id, never a branch of that name. The zero oid is 400; omit the field to mean "no parent" or "HEAD".
  • author and committer are {name, email, tz?, time?}. tz is +HHMM or -HHMM in the civil range −12:00 through +14:00 (ply's validateIdent; a bad zone is 400 bad_request). time is unix seconds. Omitted tz is +0000. Omitted time is now. Merge and rebase write each stamp with its own time and zone.
  • One edit is {path, find, replace}. An empty or omitted find creates the file (content, or replace, or empty). delete: true deletes it. to renames it. mode is 100644 (default), 100755, or 120000. Several changes go in changes: [{op, path, content?, find?, replace?, to?, mode?}] with op of create, write, edit, delete, or rename, applied in order. Pass changes or a single path, not both. A distinct committer is written on the commit. One find/replace of an existing file still streams through ply.
  • base omitted on a missing ref is a root commit (no parent), pushed with compare-and-swap old oid all zeros. base as another branch, or as a 40-hex commit, starts a new ref whose parent is that commit. base of zeros is 400 and nothing is fetched. On an existing branch, omit base to commit on the tip.
  • Every /v1 response is cache-control: no-store (a credentialed API: nothing it answers is stored, not even a tree/read/commit at a full oid). Every response carries x-ply-version (the Workers version id, which the canary checks) and x-ply-build (ply=<commit> ply-web=<commit>, injected at build time). x-ply-trace is omitted when it would be empty.
  • head on edit is a precondition: if the branch is not at head, the response is 409 cas_conflict and nothing is pushed. head of zeros means the ref must not exist yet. hint is ply's soft head hint for a one-file edit.
  • Every write shares {outcome, ref, oid, oldOid, noop}. newCommit and oldCommit are deprecated aliases of oid and oldOid. onto is a deprecated alias of the commit the write was based on. noop is true for noop, empty, and up_to_date.

Empty repository, in order

This is the whole lifecycle against a brand-new repository. Nothing is seeded with stock git. Replay it against Artifacts after deploy (Git-Token is the Artifacts bearer). Pass oids from responses into later requests.

  1. GET /v1/commit?remote= → 200 {empty:true, ref:"refs/heads/main", oid:null, tree:null, parents:[], author:null, committer:null, message:null, signed:false}. GET /v1/commit?remote=&ref=main is the same body. GET /v1/commit?remote=&ref=nope is 404.
  2. POST /v1/edit {remote, message, author:{name, email, tz, time}, changes:[{op:"create", path, content, mode?}, …]} → 200 {outcome:"commit", ref:"refs/heads/main", oid, oldOid:null, newCommit, oldCommit:null, noop:false, tree}. The ref is created with compare-and-swap old oid 000…0 and the commit has no parent. A 40-hex base is that parent commit. 000…0 is 400.
  3. POST /v1/edit {remote, message, author, committer:{name, email, tz, time}, changes:[{op:"edit", path, find, replace}, {op:"create", …}, {op:"delete", path}, {op:"rename", path, to}]}.
  4. POST /v1/branch {remote, ref, from} → 201 {outcome:"created", ref, oid}. from is a branch or a 40-hex commit. Omit from only when HEAD is born. 000…0 is 400 and nothing is pushed. An existing ref is 409 {code:"ref_exists", retry:"no", oid}.
  5. DELETE /v1/branch {remote, ref, oid} — a stale oid is 409 {code:"stale_expected", retry:"fresh", expected, actual, oid:actual}.
  6. POST /v1/tag {remote, name, target, annotated?, message?, tagger?} and DELETE /v1/tag {remote, name, oid?}.
  7. POST /v1/merge {remote, ref?, from, author, message?}.
  8. POST /v1/rebase {remote, ref, onto?, committer, squash?, message?}.
  9. POST /v1/cherry-pick {remote, ref?, commit, committer, message?, allowEmpty?} — a patch already applied, when both sides added and deleted the same paths, is 200 {outcome:"empty", noop:true, oid:<tip>}. allowEmpty:true writes an empty commit (same tree, new commit). A target branch that also has its own adds or deletes is 409 merge_conflict: ply will not guess which rename git would pair. allowEmpty does not apply to that 409.
  10. POST /v1/revert {remote, ref?, commit, committer, message?, allowEmpty?}.

An empty repository's HEAD is an unborn symref only when the server advertises ls-refs=unborn (git's default, and git's own client sends the argument only then). The first HEAD read against an origin in an isolate pays one info/refs GET so ply can see that bit (git.upload-pack discover in the trace, phase ls-refs in x-artifacts-ray and Server-Timing). The bit is remembered for the isolate and passed back to ply, so later HEAD reads on that origin are the ls-refs alone. A server configured lsrefs.unborn=allow or ignore is reported as an absent HEAD, matching git ls-remote.

GET / prints the same sequence.

  • JSON request bodies are capped at 1 MiB (413 above that). WRITES (a text binding in cloudflare.config.ts) must be on for the POST/DELETE endpoints; otherwise they return 501 unsupported.

Errors

Every failure is JSON {code, message, retry}. code comes from ply's error table (src/errors.ts), and retry is that table's policy: yes, fresh (re-read, then retry), no, or read (the push may have landed; read the ref back first). Merge conflicts add conflicts and reasons. match_count adds matches. auth adds upstreamStatus. cas_conflict adds expected and actual when known (null means the ref was to be, or is, absent). push_partial adds landed and rejected. The table below covers every ply code (src/status.ts is type-checked exhaustive against ply's CODES).

codeHTTPwhy this status
bad_request400input, including a refused remote
auth401 or 403, the upstream's own statusthe caller needs to know whether its credential was missing or not good enough
not_found404ref, path or repo
cas_conflict409the branch moved, so re-read and retry (retry: fresh). git 2.50 and later say incorrect old value provided; ply classifies that string as cas_conflict
ref_exists409creating a branch or tag that already exists (retry: no). The body includes oid, the current target. Checked before the push, so a lost race that Artifacts reports as stale ref is mapped here too
stale_expected409deleting a ref whose oid is not the current target (retry: fresh). The body includes expected, actual, and oid (the actual)
merge_conflict, not_fast_forward, push_rejected, push_partial409conflict with the repository's current state
match_count, lfs_pointer, not_linear, unrelated_histories422the request is well-formed but cannot apply to this content. Retrying it unchanged cannot work, even against a fresh state. That is the difference from 409
limit_exceeded413
rate_limited429
upstream_5xx, network, protocol, pack_corrupt, not_git, remote_error, http, ambiguous502the upstream misbehaved. Check retry before retrying: ambiguous is read
timeout504
aborted499the caller went away
unsupported501including writes when they are disabled
read_only403a write whose remote is in the public namespace, with or without a bearer or git credential
internal500a bug; an error without a known code is reported as this

Tracing

  • ?trace=1 on a JSON endpoint adds trace: [{name, ms, status, attrs, events}] with ply's spans: the spans ply's Tracer hands its onEnd (the plain-value form of the OTLP spans ply emits anywhere; no OTLP is built for a request).

  • /v1/read streams raw bytes and has no JSON to carry spans. Instead, ?trace=1 adds an x-ply-trace header summarising every span that finished before the first byte, as name;dur=ms, …. The blob's own span finishes after the response is sent, so it shows up only in the request's log line (stream: ok|error).

  • Every request writes one structured log line (msg: "ply.request") with id, method, path, upstream host (never the path or the credential), status, ms, round trips, how many fetches used the blob:none fallback, and pack-cache hits. Workers Observability logs and traces are enabled, and redact_query_string keeps remote= out of the platform's request records. Each response carries x-ply-request-id.

  • Every /v1 response that talked to the remote, including 4xx and 5xx, carries x-artifacts-ray and Server-Timing. The ray header is the upstream cf-ray of each git HTTP exchange, in start order:

    ray-header = entry *( ", " entry ) [ ", " overflow ]
    entry      = phase "=" ray ";dur=" duration
    overflow   = "overflow=" 1*DIGIT
    phase      = "ls-refs" / "fetch" / "receive-pack"
    ray        = cf-ray / "-" / "no-response"
    cf-ray     = 16HEX "-" 3ALPHA
    duration   = 1*DIGIT

    ls-refs is info/refs and v2 ls-refs. fetch is each upload-pack fetch, including a blob:none retry. receive-pack is the advertisement and the push. - is a response with no ray id (the raw header is not echoed). no-response is a call that failed before headers. Past 32 entries the rest are overflow=<count>. Server-Timing repeats the same phases and durations, then total for the Worker. The matching spans gain git.upstream.cf_ray, git.upstream.phase, and git.upstream.dur_ms. The viewer sends the same header. It contains no URL, credential, or repository name.

Servers that refuse filter tree:0

Cloudflare Artifacts refuses filter tree:0. ply learns this from the 400 and falls back to blob:none, which brings more trees per fetch (see ply's README). The Worker keeps what it learned per origin for the life of the isolate, so only the first request on an isolate pays for the 400.

Public viewer (/view)

GET /view is a server-rendered browser for a public smart-HTTP repository. It does not use PLY_TOKEN and it never reads Authorization, Git-Token, Git-Authorization, or Cookie. A URL with userinfo is rejected, not turned into a credential. /v1 is unchanged: same gate, same credential headers. /v1 and the viewer share one isolate-wide, per-origin quirks map (src/quirks.ts): a server that rejects filter tree:0 costs that 400 and the blob:none retry once per isolate, and later pages ask for blob:none directly (the waterfall says which). Until 2026-10-31 the viewer re-learned it on every page; on Artifacts that 400 was ~110–150 ms of every page.

The home form accepts an https URL, github.com/owner/repo, owner/repo (github.com), or git@host:path (the ssh user is dropped, then the allowlist runs). Shareable URLs: /view/<host>/<repo path>?ref=&path= (path may use / or %2F). A path segment of . or .., a backslash, or an encoded slash, backslash, or dot in the URL path (and an encoded dot or backslash in ?path=) is rejected on the r …

Recent commits10
Diagnostics4 git calls · 501 ms
CallStatusSizeTime0501 ms
discover200152 B212 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=212
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B453 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=241
git.response.bytes=145
git.response.cache=EXPIRED
git.response.duration_ms=241
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020042 KiB · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=24
git.response.bytes=42585
git.response.cache=HIT
git.response.duration_ms=25
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=262b639aa1b258fc1777c3a66ba8f811df3a3da2
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=42585
git.pkt.payload.max=42490
git.sideband.band1.bytes=42489
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=42489
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=7dbf576d97429022615f79aa46b440d9da603496
git.pack.full=61
Open pack map
fetch20018 KiB · hit23 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=23
git.response.bytes=18392
git.response.cache=HIT
git.response.duration_ms=23
git.fetch.wants=0011567de753332ba7afea098081dffcc62caa2b
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=18392
git.pkt.payload.max=18371
git.sideband.band1.bytes=18370
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply-web.git
Ref
refs/heads/main
Commit
262b639aa1b258fc1777c3a66ba8f811df3a3da2
cf-ray
a5e0f81b2d20332c
Request
3b149e69…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format