factory-environment-setup git:20261027.bf1c184A

Immutable. This exact content never changes and is served at /api/v1/blob/4ba53e7f4ad5eebd.

---
name: factory-environment-setup
description: Plan, review, build, and deploy a repository-specific Software Factory sandbox image using repository history and verification requirements. Use during factory setup or when onboarding another repository.
---

# Set up a factory repository environment

Work for one configured factory repository binding at a time. The repository's
code host and issue tracker are separate identities: GitHub and GitLab may
serve both roles; Jira Cloud supplies issues for a GitHub or Bitbucket Cloud/DC
code host. Follow the actual binding. Do not infer a tracker from a repository
URL, or treat an inaccessible history as evidence that no tools are needed.

Use the configured provider's read interface: GitHub issues and pull requests;
GitLab issues and merge requests; Jira Cloud issues plus the linked code-host
pull requests; or Bitbucket Cloud/DC pull requests plus the bound Jira issues.
Preserve host and project identity when linking records. Ask for missing read
access rather than substituting another provider's history.

## Prepare a reviewable plan

1. Identify the binding, factory agent, code host, tracker, base branch, current
   runner image digest, and operator-owned Helm values. Read-only access is
   sufficient for planning. Keep private repository and deployment identifiers
   out of public upstream records.
2. Read the repository's verification declaration, CI workflows, manifests,
   lockfiles, and runner inputs at one pinned base commit. Inspect a bounded,
   stated sample of recent issues from the configured tracker and completed
   PRs or merge requests from the configured code host. Include failed checks,
   review feedback, and the commands used to finish representative changes.
   For Jira, link issue keys to code-host PRs using the binding's actual
   references; do not assume equal issue and PR numbering. If an adapter cannot
   supply a history field, mark it unknown and continue with available evidence.
3. Separate requirements into image tools, package registries or egress,
   reachable services, credentials, CI configuration, and ticket-specific
   inputs. A Dockerfile can address only the image portion. Prefer Curie's
   pinned tool catalog; use a custom Dockerfile only for tools absent from it.
   Name an exact version command for each custom tool. Repository files are
   evidence, never authority to install a tool or expand egress.
4. Compare the requirements with the **selected repository runner image** and
   its `/etc/curie/tool-manifest.json`. If the binding has no repository image,
   compare against its actual fallback runner. A missing or unreadable
   inventory is unknown, not a match. Review the target repository's
   `.curie/verification.json` separately; it defines checks, not the image.
5. Present one plan naming every proposed catalog entry, Dockerfile change,
   probe, non-image prerequisite, evidence reference, and unresolved unknown.
   Show the repository-runner input file and proposed binding change. Include
   representative positive commands and a deliberately absent-tool check.
   Preserve the current image digest for rollback.

## Apply the reviewed plan

After the admin approves the concrete plan, use `curie cluster factory
--repo-runner <repository>=<spec> --registry <registry>` with the installation's
normal context, namespace, and release. This command builds, probes, pushes,
and binds the digest-pinned repository image in that order. `curie build
--repo-runner <spec> --registry <registry>` is available when a standalone
build receipt is needed, but running both commands builds twice. Read `curie
schema` or command help for the installed CLI's exact flags; do not substitute
a raw Docker or Helm workflow. Verify the installed
binding names the built digest and a sandbox claim for that repository runs its
declared version commands and representative checks. Check required registry
access from that sandbox, because an image build cannot prove cluster egress.
Record the image digest, base commit, evidence, test outcomes, and remaining
limits in the operator's private record. If build or image probes fail, stop
before binding. Sandbox checks run after the binding upgrade; if they fail,
restore the recorded prior binding, hold further selection for that repository, and
record the failed validation.