Appearance

How to keep resources reproducible ​

Pin a repository's resources to exact Git commits so every clone and every CI run produces the same files.

Prerequisites ​

  • A repository with .agents/config.yaml already configured (see how to adopt agent-marketplace in a repository).
  • At least one remote Git registry in that configuration. Directory sources are read live and never appear in a lock.
  • agent-marketplace v4.0.9 or newer everywhere the lock is read, including CI. Sync writes the lock in the agent-marketplace-lock/v2 format, and older versions cannot read it.

1. Commit the generated lock ​

Run a normal sync to create or update .agents/lock.yaml:

bash
agent-marketplace sync

It prints the usual Installed <n> Removed <n> Malformed <n> Errors <n> summary, plus a → line when it writes or removes output. It also writes .agents/lock.yaml. Check that the file exists:

bash
test -f .agents/lock.yaml && echo "lock present"

Expected:

text
lock present

Commit the lock with the configuration:

bash
git add .agents/config.yaml .agents/lock.yaml
git commit -m "Lock agent-marketplace dependencies"

git add prints nothing; git commit prints its usual [<branch> <hash>] Lock agent-marketplace dependencies summary.

If the repository has an older agent-marketplace-lock/v1 lock, the next writing sync or lock rewrites it as v2. Until then, lock --check reports lock.version-upgrade-required. Commit the rewritten lock too.

2. Verify lock freshness in CI ​

A fresh CI runner has the committed configuration and lock, but no cache of registry snapshots and no ignored harness output. For Git sources, sync --check fetches nothing. Run alone, it fails even on a healthy checkout, with lock.snapshot-unavailable or output drift. Prepare the checkout first, then check it:

bash
agent-marketplace sync --locked
agent-marketplace sync --check
  • sync --locked fetches the exact commits recorded in the lock and writes the harness output, printing the usual Installed ... summary. It never writes configuration or locks. If the committed lock is missing, it fails with lock.missing. If the lock no longer matches the configuration, it fails with lock.stale. Either way the CI job fails at this step.
  • sync --check then compares the prepared checkout with what sync would produce. A healthy checkout prints no drift report and exits 0. A stale lock or missing or extra output exits 1 and prints the reason.

Do not prepare the runner with a plain agent-marketplace sync. A plain sync updates a stale lock in place, which hides the problem the CI job should catch.

3. Advance locks on purpose ​

A lock keeps its commit when the branch or tag it came from moves. To move a Git registry to the commit its ref points to now:

bash
agent-marketplace lock --upgrade

It prints Locks: <n> changed, for example Locks: 0 changed or Locks: 1 changed. The default scope includes user, repository, and personal-local locks, so the count can exceed one. lock --upgrade changes only locks. Run agent-marketplace sync afterwards to update the harness files, or use agent-marketplace update, which advances the locks and syncs in one step. Then commit the updated .agents/lock.yaml.

To review the change before you apply it, see how to review and roll back an update.

4. Avoid editing locks by hand ​

The CLI generates the lockfile. Editing it by hand bypasses the checks the CLI makes against the source, and is not supported.

Troubleshooting ​

  • If sync --check reports lock.snapshot-unavailable, the exact snapshot is not in the cache. Run agent-marketplace sync --locked to fetch it without touching configuration or locks. If updating the lock is acceptable, run a writing agent-marketplace sync or agent-marketplace lock instead.
  • If the lock changes although nobody changed the configuration, someone ran agent-marketplace lock --upgrade or agent-marketplace update. A healthy lock never moves on its own when main moves. Commit the result if the change was intended.
  • If CI fails with lock.invalid-document, check agent-marketplace --version (it prints the installed version) in the CI job first. Versions older than v4.0.9 cannot read the lock, so upgrade the job. If the version is current, the lockfile itself is damaged. See the lockfiles reference for the format and every lock error.