Recipe: onboard a client repository

The scenario: a client hands you a repository. You have never run it, you do not know what is in its history, and you need to be delivering against it this week — without their credentials ending up somewhere they should not be.

This recipe is the safe path, in the order the risks actually arrive.

Prerequisites

• A hlix workspace and an API key
• The client’s repository checked out locally
• Agency owner or admin if you will also connect GitHub

The recipe

1. Look before you upload. The first command is not an import.

   cd path/to/client-repo
   hlix import . --dry-run

   Read three things in the report: history findings, protected files, and quarantined resources. A client repository is exactly where a committed .env from two years ago shows up.

2. Deal with what the scan found — do not override it.

   If history findings appear, the credential is in the Git history and anyone with that history can recover it. --history preserve uploads the history despite the findings; it does not remove them. Rotate first, with the client, then re-scan.

   hlix import . --dry-run --history abort-on-findings

   Expected result: no blocking findings. That is the gate for continuing.

3. Import for real.

   hlix import . --name "Acme — storefront"

   Expected result:

   Imported Acme — storefront
   Project ID: 6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
   Revision: 1

   Protected files travelled the encrypted path and are out of the Git bundle. Quarantined resources — any AGENTS.md, skill, or .mcp.json the client’s repo carried — are preserved but inert.

4. Decide what you trust. The client’s repository may contain agent instructions written by someone else. They do nothing until you activate them, and you should read them before you do.

   hlix agent import AGENTS.md --name "Acme builder"

   Skip this step entirely if you would not hand those instructions to a contractor.

5. Attach it to the client account in the dashboard, under Customers, so the project appears in that client’s grouping and their portfolio rolls up correctly.

6. Ship one small thing first. Not the big refactor. Pick a change whose correctness you can judge at a glance, so the first review tells you whether the setup is right rather than whether the change is right.

   Start the run from the dashboard, or over the API:

   curl -sS -X POST "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/start" \
     -H "x-api-key: $HLIX_API_KEY" \
     -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
     -H 'content-type: application/json' \
     -d '{"brief":"Add a health endpoint at GET /healthz returning 200 with the build SHA, and cover it with a test."}'

7. Read the evidence, not the summary.

   hlix tasks list
   hlix tasks review <task-id>

   The files[].patch is the diff read back from the repository host — an observation, not the agent’s account of itself.

What this buys you

• The client’s secrets never entered a commit, and you found the historical ones before they became your problem.
• Someone else’s agent instructions did not silently start steering your delivery.
• The first change was small enough that a bad result told you about your setup.

`--yes` is not a way past a blocker

In CI you will want --yes, and it is the right flag for approving a reviewed upload. It does not override history findings, unsafe paths, integrity failures, or size limits. If an import is blocked, the blocker is the message — not the flag.

If the recipe stalls

• scan_blocked on a repo the client swears is clean — the blocker list names each finding. See If the scan blocks the import.
• already_imported — the folder is bound from a previous attempt. Use hlix push, or delete the cloud project and re-import.
• The first task never runs — a task must come from a cycle. A project run creates them; a standalone task does not execute. See Tasks.
• Review evidence says it cannot verify the branch — the project has no connected remote yet. Connect GitHub, or read the downloadable workspace archive instead.

Next steps

Import trust modelWhat import reads, executes, and makes active — the full boundary.

Parallel cycle deliveryThe next recipe: many tasks at once, without collisions.

Reviewing outputLine-level comments and sending a task back for a revision.

GitHubConnect the repository so tasks land as branches and pull requests.