Repo-to-Running-Service Guide

Convert an unfamiliar repository into a reproducible setup, launch, test, and deployment plan without guessing at dependencies.

The result you're building

A clean-room runbook that takes a freshly copied repository to a healthy local service using pinned dependencies, explicit configuration, a repeatable start command, a functional test, and a documented deployment boundary.

Use this guide when

• A repository has incomplete, stale, or contradictory setup instructions.
• You must evaluate client software without trusting install scripts blindly.
• The project works on one machine but cannot be reproduced elsewhere.

Do not use it as a substitute for

• Executing an unknown repository on a production host or with valuable credentials.
• Assuming a successful build proves the service is safe, correct, or deployable.

Before you change anything

• Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.
• Repository URL or local source plus exact commit hash.
• README, lockfiles, manifest files, container files, migrations, and example environment files.
• A disposable user account, container, VM, or sandbox with no production secrets.
• Expected service behavior, health route, ports, and external dependencies.
• Permission to use required third-party services and licenses.

Understand the system before fixing it

The repository is evidence, not documentation
Manifests, lockfiles, imports, CI configuration, and entry points often reveal the actual runtime more reliably than prose. Conflicts must be recorded and resolved explicitly.

Build, start, healthy, and correct are separate gates
A compilation proves syntax and dependencies. A running process proves only that it did not exit. A health endpoint proves a narrow check. Functional tests prove the requested behavior.

Configuration is part of the product
Environment variables, migrations, ports, storage, callbacks, and external service assumptions must be versioned as a schema even when secret values are excluded.

Evidence-to-decision map

Step-by-step procedure

Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.

Step 01 — Fingerprint the repository without executing it

Why: File structure identifies language, package manager, build path, and risky hooks.

Do: Record the commit, list top-level files, inspect manifests and scripts, and search for shell execution, network fetches, migrations, and secret names.

git rev-parse HEAD
find . -maxdepth 2 -type f | sort | sed -n '1,200p'
rg -n 'postinstall|curl |wget |migrate|seed|PRIVATE_KEY|TOKEN' .

Read the result: Lockfiles identify the expected package manager; multiple lockfiles are a reproducibility warning.

Next: Choose a runtime and sandbox before installing.

Step 02 — Write the environment contract

Why: A .env.example name without meaning or validation does not tell an operator what is required.

Do: For every variable record type, required/optional status, safe example, consumer, and failure behavior. Separate secrets from ordinary configuration.

rg -n 'process\.env|os\.environ|getenv|env::var|VITE_|NEXT_PUBLIC_' .

Read the result: If a variable affects destructive destinations, authentication, billing, or networks, it requires explicit validation and a safe default of refusal.

Next: Create only test values and isolated dependencies.

Step 03 — Install exactly from the lockfile

Why: Regenerating dependencies can hide the real state and introduce unrelated changes.

Do: Use the package manager and frozen/locked mode specified by the repository. Capture the runtime and dependency versions.

python3 --version; node --version 2>/dev/null; cargo --version 2>/dev/null
npm ci   # or: pnpm install --frozen-lockfile
python3 -m pip install --require-hashes -r requirements.txt

Read the result: A frozen install failure means the repository is not reproducible as committed; preserve that result before deciding to update.

Next: Do not run the service until install hooks and native-build output are understood.

Step 04 — Run preparation stages separately

Why: Combining build, migration, seed, and start makes it impossible to identify which stage failed.

Do: Run lint/typecheck, build, migration status, migration, and start as separate recorded steps. Back up any non-disposable database before migrations.

npm run lint --if-present
npm run build --if-present
npm run start --if-present

Read the result: The first failed stage owns the next investigation. Do not skip it just because a later command can start.

Next: Start with localhost-only binding and test configuration.

Step 05 — Prove health and one real outcome

Why: A listening port can still serve errors or talk to the wrong database.

Do: Check the listener, health route, logs, and one representative create/read or request/response flow using disposable data.

ss -ltnp
curl -fsS http://127.0.0.1:PORT/health
curl -i http://127.0.0.1:PORT/CORE_ROUTE

Read the result: Confirm the response, persistence side effect, and log correlation ID agree.

Next: Record the exact start and test commands.

Step 06 — Convert discovery into a handoff runbook

Why: The setup is not complete if only the original investigator can repeat it.

Do: Write prerequisites, setup, config schema, start/stop, health, backup, migration, test, and recovery steps from a clean checkout.

Read the result: A second clean run should need no undocumented clicks or remembered values.

Next: Only then choose the production deployment shape.

Worked example

Evidence collected

• package-lock.json pins Node-compatible dependencies and npm ci succeeds.
• The service reads DATABASE_URL; .env.example lists it but no local database setup.
• A migration script exists and CI provisions PostgreSQL before tests.
• No process is listening on local port 5432.

Decision: The application build is valid; the missing runtime dependency is PostgreSQL configuration and initialization.

Actions taken

• Started an isolated PostgreSQL container with a disposable database.
• Set a test-only DATABASE_URL, ran migration status, then migrations.
• Started the API on localhost and exercised its health and one database-backed route.

Why this example matters: The useful output is not it runs on my machine; it is a dependency and configuration contract another operator can reproduce.

Verify, recover, and hand off

Completion tests

• A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.
• A clean checkout at the recorded commit installs without modifying the lockfile.
• Required configuration fails fast with a useful message when absent.
• Build, migrations, and start each have distinct commands and logs.
• Health and one core functional test pass against disposable dependencies.
• No production secrets or datasets entered the evaluation environment.

Rollback or safe recovery

• Destroy disposable dependencies rather than trying to clean them manually.
• Restore database backup if an authorized migration changed non-disposable data.
• Return to the original lockfile and runtime when an update attempt fails.

If the expected result does not appear

Reusable handoff record

• Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.
• Repository origin and exact commit.
• Runtime, package manager, and frozen-install command.
• Configuration schema with safe examples and secret boundaries.
• Build, migration, start, stop, health, and core-test commands.
• Known limitations, deployment assumptions, and rollback steps.

Agent delivery contract

Required inputs

Returned output

Agent refusal and escalation rules

• Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
• Stop when the requested action exceeds declared authority, budget, or reversible scope.
• Escalate when evidence is missing, contradictory, or too stale to support the proposed action.

Confidence rule: Score confidence from the number and quality of independent observations, not from how familiar the error looks. Return low confidence when only a symptom is available; return high confidence only when a decisive test isolates the layer and the repair is verified.

Official reference starting points

• https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
• https://docs.npmjs.com/cli/v11/commands/npm-ci
• https://packaging.python.org/en/latest/tutorials/installing-packages/