[saurabhmaheshwari-obin]

What

A build recipe can now declare the locked git sources its build needs: DockerBuildRecipe.git_source_downloads, a list of GitSourceDownload { repository, commit, mirror_context }. The caller fetches each commit into a bare mirror on its own machine, with its own credentials, before any image build, and supplies the mirrors as a named build context. The build then resolves those sources from the mirrors and needs no credential.

This is the git counterpart of GoModuleDownload (core#677, contract v5), built the same way:

	Go module download (v5)	git source download (v6, this PR)
declared in	DockerBuildRecipe.go_module_downloads (field 10), WithGoModuleDownloads	DockerBuildRecipe.git_source_downloads (field 11), WithGitSourceDownloads
fetched by	the caller, on the host, with the host's credentials	the same
reaches the build as	a named build context (gomodproxy), no secret	a named build context (for example uvsources), no secret
contract	v5, emitted only when declared	v6, emitted only when declared, and above v5 when both are
digest	module root and proxy context, in order	repository, commit and mirror context, in order (v6 also covers v5's and v4's fields)
validation	validateGoModuleDownloads, in validateRecipes	validateGitSourceDownloads, in validateRecipes
old host	refuses a v5 plan (fails closed)	refuses a v6 plan (fails closed)

Also in this PR:

• GitSourceMirrorPath(repository), which returns <sha256 hex>.git, and GitSourceMirrorRef(commit), which returns refs/commit/<commit>. They give the host and the Dockerfile one definition of the mirror layout.
• GitSourceRepositoryProblem(repository) and IsGitSourceCommit(commit), the validator's own checks exported. An agent reading a lockfile checks a source before declaring it, and leaves one the contract cannot carry to the build's own fetch, instead of failing the plan after rendering.
• SingleImageBuildResponse takes variadic RecipeOptions; existing callers are unchanged.
• agents/contract/contract.json and docs/agent-contract.md record recipe v5 and v6.

Why

Issue: codefly-dev/service-python-fastapi#102. A Python service whose uv.lock pins a private git source cannot be built into an image today. The builder stage runs uv sync --frozen with no credential and no prefetched input. The caller usually holds the credential, but nothing that credential can read reaches the build.

Go services with private modules build today because the caller prefetches the module graph. This PR adds the same declaration for locked git sources.

We tested carrying a prefetched uv cache into the build first. It works only when the host's uv matches the image's uv exactly and the wheels are fetched per target platform; caches from uv 0.9 and 0.13 both failed in a 0.12 image. A bare git mirror at the locked commit, mapped in with url.<mirror>.insteadOf=<locked url>, worked with an empty cache, no network route to the source and the lockfile untouched. It depends on nothing in uv's internals, and it carries only the part that needs the credential. Public package indexes stay on the network, as in every build today.

The message is generic rather than Python-specific. Any lockfile that pins git sources by commit (Cargo, npm, Go replace to a git URL) can declare the same thing.

Deviations from the Go module download path, with reasons

• Uniqueness on (repository, commit, context). Go refuses a repeated proxy context, because one context holds one module graph. One mirror context holds many repositories, and a repository can be locked at several commits, so only an exact repeat is refused.
• A mirror context must not equal a Go proxy context in the same recipe: one named build context cannot be both a module proxy and a mirror set.
• A strict URL allowlist, and errors never echo the URL. A Go module root is a relative path that never leaves the recipe. A repository URL is handed to the host's git and written verbatim into the Dockerfile's git configuration, and a pasted URL may carry a token.
  • Only lowercase https:// and ssh:// are accepted, with no userinfo over https, no password, and no query or fragment.
  • The path is limited to [A-Za-z0-9._~/:+-]. Percent-escapes are refused anywhere in the URL, and @ is refused after the authority, because git decodes escapes before it splits an ssh URL into user, host and path; an encoded @, [ or / could otherwise change the host after validation.
  • A lockfile URL that really needs an escape (a repository name with a space, for example) is refused at plan time, never fetched over the network.
  • Errors name the declaration by its position.
• git+ssh is not accepted. Lockfiles record the URL git is handed, without a git+ prefix, and the build maps exactly that URL onto the mirror, so an alias would never match.
• v6 always digests the Go section and the context root. This follows v5, which digests v4's root: each version's digest layout is a superset of the one before.
• SingleImageBuildResponse gains variadic RecipeOptions. Existing callers compile unchanged, and agents that use the single-image helper can declare downloads without copying the plan code.
• GitSourceMirrorPath / GitSourceMirrorRef helpers. Go's proxy layout is defined by Go. A mirror layout is not, so the host and the Dockerfile share one definition.
• contract.json and docs/agent-contract.md record v5 as well as v6. v5 was supported but never recorded.

Release order (please read)

A CLI must not pick up this core without the matching host fetch. Otherwise it would accept v6 plans without supplying the mirrors, and the build would fall back to the network. The Go change closed the same gap by landing core#677 and the CLI change together. Companion PRs:

• CLI: fetches declared git sources on the host and passes the mirrors as a build context: feat(build): fetch declared git sources on the host and hand the build a mirror context cli#1106 (draft);
• python-fastapi agent: declares the uv.lock git sources and maps them onto the mirror: feat(builder): declare uv.lock git sources for the caller to mirror service-python-fastapi#103 (draft).

Testing

• go test ./agents/services/ ./agents/contract/ and go test -race ./agents/services/. The new docker_recipe_git_sources_test.go covers:
  • v6 only when declared;
  • verifier acceptance, and refusal of downgraded plans (v3, and v5 when Go modules are also declared);
  • the digest catches a change to every field;
  • combination with Go modules;
  • each refusal, including credential URLs whose secret must never appear in the error, and percent-encoded authority tricks;
  • accepted forms, and mirror path and ref determinism.
• v3 to v5 contract versions and digests are byte-identical to main for recipes that declare no git sources.
• make buf-lint, and make buf-breaking ("no breaking change against origin/main").
• The Python contract tests (test_*_contract.py).
• Generated code comes from codefly generate proto --proto ./proto --output ./generated --local (plus the Python template).

Not in this PR, and not verified here:

• The generation run also moves proto/buf.lock (a googleapis pin) and regenerates runtime_pb2.py, which is already out of date on main. Both were reverted, to keep this change focused.
• Locally, agents/manager TestNewNixStoreFromEnv_SetReturnsStore needs nix, and three internal/ciguard tests need bash 4 (mapfile). They fail the same way on main on this machine.
• The CLI host fetch and the agent's BuildKit build are in the companion PRs.

CI notes (run on the fork, head abdc7077: https://github.com/saurabhmaheshwari-obin/core/actions/runs/39681236215)

Every test step in Build passes, and pnpm source evidence passes. Two steps fail, neither because of this change:

• Proto, breaking-change guard: the script refuses to run unless origin is this repository ("BASE_REMOTE=origin is not codefly-dev/core"), so it can only pass here. Locally, against this repository's main, it reports "proto: no breaking change"; the change is additive (field 11 and a new message).
• Build, govulncheck: GO-2026-6809 (crypto/x509) is fixed in go1.27.3, and go.yml installs 1.27.2. The finding is in code this PR does not touch. main's last run predates the advisory, so main would report the same today. Bumping the CI Go version is left to a separate change.

Review

• Side-by-side check against the Go module download path, at this head: aligned. Every dimension matches, citing core#677's code and the CLI and go-grpc consumers: where it is declared, the plan phase, the host's credentials, the named build context with no secret, digest, validation, contract versioning, old-host behaviour (fails closed) and tests. The deviations above are the complete list.
• Codex (xhigh), three rounds.
  • Round 1: a credential echo in errors, and scheme-case acceptance. Both fixed.
  • Round 2: percent-encoded brackets that change the ssh authority. Fixed.
  • Round 3: no P1 or P2. Two P3s (port range, a login or host starting with -) fixed with tests.
  • Round 4, the exported checks: none; the wrappers match the validator exactly.

Classification: a fix. It closes a gap where a declared build input could not reach the build.

🤖 Generated with Claude Code